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Preface 



The PATtiWORKS for Macintosh: MacX User's Guide describes how to use MacX™, an 
X Window System server developed by Apple Computer for the Macintosh® family of 
computers. The Preface summarizes what you'll find in the MacX User's Guide, gives 
suggestions for using the guide, and presents a road map that shows how the different 
parts of the guide fit together. The Preface also tells you how to find more information 
about the X Window System, DEC windows™, programming in the X environment, and 
using MacX with different operating systems. 



About this guide 

The PATHWORKS for Macintosh: MacX User's Guide is a special edition of the MacX 
User's Guide distributed by Apple Computer. This special edition was created for the 
PATHWORKS™ for Macintosh product and is an adaptation (for use in the DECwindows 
environment) of the general version of the MacX User's Guide. 

Although the MacX software sold by Apple is virtually identical to the MacX software 
provided as a part of PATHWORKS for Macintosh (the only differences being the set of 
fonts provided, the communications software provided, and the default connection 
method), the two manuals differ in many places. Most importantly, the PATHWORKS for 
Macintosh version of the guide provides instructions and examples for using 
DECwindows applications, as opposed to other types of X clients. 

If you are using MacX to connect to X environments running under a UNIX operating 
system, or using TCP/IP connections, you may want to refer to the general version of the 
MacX User's Guide. See also "For More Information" later in this Preface. 
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What you need to know 



The MacX User's Guide is intended for Macintosh users who may or may not be familiar 
with Digital Equipment Corporation computers. A basic understanding of computer 
networks will be helpful to you. If you need an overview of network terms and concepts, 
you may want to read Appendix A in the PATHWORKS for Macintosh: Network Services 
User's Guide. 

If you are new to the Macintosh computer, see your owner's guide for information on 
setting up your computer. You may also want to use the tutorial disk that came with your 
Macintosh to learn how the Macintosh operates. You should be familiar with basic 
Macintosh techniques such as clicking, double-clicking, and dragging with the mouse; 
working with windows; pulling down menus and choosing commands; and using the 
Clipboard to store information. For information on Macintosh terms and techniques, see 
the Macintosh System Software User's Guide. 

This guide explains how to use MacX to gain access to DECwindows applications. If you 
have never used X programs before, you need to learn a little about the X environment 
before you use this guide. You should know how to use DECwindows applications and 
how to interact with the operating system under which the DECwindows applications 
run. For example, if you are connecting to DECwindows running under the VMS™ 
operating system, you should be familiar with Digital Command Language (DCL) 
commands, which let you interact with VMS. Consult the VMS User's Manual, the VMS 
DECwindows User's Guide, and the guides for the particular DECwindows applications 
that you want to use. 

For information on installing MacX and other Macintosh software components for 
PATHWORKS for Macintosh, see the Installation part of the Network Services User's 
Guide. 



How to use this guide 

Your experience with the X Window System (also known as X), computers, and 
networks will determine the way in which you use this guide. This section suggests two 
basic approaches — one for beginners and one for experienced users. The road map in 
the next section should also help you determine the best way to use this guide. 
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For the beginner 

If you're not familiar with the X Window System, read the guide in the following order: 

1. Read Chapter 1, which briefly covers what X is and how it works. This chapter 
explains how MacX differs from traditional implementations of X and contains a 
summary of MacX features. 

2. Read Chapter 2, which explains the essentials that you need to know to run clients on 
a Macintosh computer. You may also need to refer to one of the modules in the 
Connection Tools Reference in this binder when reading Chapter 2. 

3. Browse through the other chapters at your convenience to learn about other useful 
features. For descriptions of the other chapters and appendixes, see the "Summary of 
Contents," later in this Preface. 

For help with network terms and concepts, refer to Appendix A in the Network 
Services User's Guide. 

For the experienced user 

If you have a technical background or extensive X experience, you have a couple of 
options. 

■ You can go directly to Chapter 3 for instructions on creating remote commands. 
Chapter 3 gives an expanded version of the information in Chapter 2 (which is a 
tutorial), except for the sections on starting MacX and on quitting MacX. You might 
want to read those sections in Chapter 2. 

■ You can read "Introducing MacX" in Chapter 1 to learn how MacX differs from 
standard X implementations. 

Basically, you can get the introductory information that you need from the first two 
chapters and then concentrate on the other chapters and appendixes, where specific 
features are documented in detail. The Connection Tools Reference in this binder 
provides information on the connection tools that you use with MacX. 
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Summary of contents 

The following list describes what's covered in the MacX User's Guide: 

■ Chapter 1, "MacX Overview," briefly describes the X Window System, introduces 
MacX, and presents an overview of MacX features. This chapter also describes 
differences in the way that the mouse and keyboard function when you use MacX. 

■ Chapter 2, "Getting Started," covers basic information that you need in order to use 
MacX in the DECwindows environment. It describes how to start MacX, create a 
remote command to start the Session Manager, close applications, and exit from 
MacX. 

■ Chapter 3, "Using Remote Commands," describes how to create, execute, and edit 
remote commands by using the Remote menu and the Remote Command dialog box. 
It also covers MacX security features. 

■ Chapter 4, "Working with Windows," explains how to move and resize windows, 
select window styles, convert windows to icons on the screen, and change the icons 
back to windows. This chapter also discusses the use of root windows. 

■ Chapter 5, "Managing Fonts and Color," tells you how to use fonts and color in MacX. 
It tells you how to perform various tasks with the Font Director and Color Namer— for 
example, adding and removing fonts and colors, creating aliases for font names, and 
so on. 

■ Chapter 6, "Troubleshooting," offers suggestions for correcting problems that you 
may encounter while using MacX. 

■ Appendix A, "MacX Versus Other X Servers," explains the differences between MacX 
and conventional X servers. 

■ Appendix B, "The MacX Window Manager," covers some technical aspects of the 
MacX Window Manager. 

■ Appendix C, "Bitmap Distribution Format 2.1," contains the X Consortium document 
that describes the format of BDF files. 
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■ Appendix D, "X Logical Font Description Conventions," contains the X Consortium 
document that specifies the format of X font names. 

■ Appendix E, "Character Conversion Charts," shows the hexadecimal equivalent for 
each character in the ISO Latin 1 and Macintosh extended ASCII character sets. The 
appendix also contains two character-mapping charts. 

■ The Connection Tools Reference describes the connection tools that let you establish 
communications with X clients. 

■ The User Update is where you can put late-breaking and supplemental information 
for the MacX User's Guide. 



Visual conventions used in this guide 

The Courier font is used to indicate computer commands and text that you type. 

Terms that have a special meaning in relationship to Macintosh or Digital computers, or 
to networks, appear in boldface at first mention or when first defined in the text. These 
terms are defined in the glossary. 

The MacX User's Guide includes special text elements to highlight important or 
supplemental information: 

♦ Note Text set off in this manner presents additional information or interesting 
sidelights. ♦ 

Important Text set off in this manner— with Important— -presents important information 
or instructions. A 
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For more information 



This section lists manuals that offer basic information about DECwindows and about 
running clients under a UNIX operating system; references for X programmers; manuals 
on XI 1 for A/UX®, MacX for UNIX, MacX for A/UX. This section also describes a Usenet 
news group offering information about the X Window System. 

Basics 

For information about DECwindows applications, refer to these manuals: 

■ VMS DECwindows User's Guide. Digital Equipment Corporation, October 1989. (VMS 
Version 5.3.) 

■ VMS DECwindows Desktop Applications Guide 

Also see the manual provided by Digital for each DECwindows application. 

For a tutorial on starting a server and running standard clients under a UNIX operating 
system (such as ULTRIX™), read the following manual: 

■ X Window System User's Guide, Volume Three. O'Reilly & Associates, Inc., 1988. 
X programming 

For information on X programming, see the following manuals: 

■ Scheifler, Robert W., James Gettys, and Ron Newman X Window System: C Library 
and Protocol Reference. Digital Press. 

■ Xlib Programming Manual, Volume 1. O'Reilly & Associates, Inc. 

■ Xlib Reference Manual, Volume 2 . O'Reilly & Associates, Inc. 

■ X Toolkit Programmer's Guide. O'Reilly & Associates, Inc. 
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Programmers may also find the following documents useful. You may order them directly 
from the Massachusetts Institute of Technology (MIT); contact information follows. 

■ Using the X Toolkit 

■ X Toolkit Widget 

■ X Toolkit Intrinsics 

■ Inter-Client Communications Conventions Manual. 

MIT Software Center 
Technology Licensing Office 
77 Massachusetts Avenue 
Cambridge, MA 02139 

Digital Equipment Corporation publishes a set of volumes that cover similar topics from a 
DECwindows perspective: 

■ DECwindows Programming Volume 1A 
>- VMS DECwindows XUI Style Guide 

□ VMS DECwindows Guide to Application Programming 

- VMS DECwindows User Interface Language Reference Manual 

■ DECwindows Programming Volumes IB and 1C 

- VMS DECwindows Tookit Routines Reference Manual, Part I 
c VMS DECwindows Tookit Routines Reference Manual, Part II 

■ DECwindows Programming Volume 2A 

c VMS DECwindows Xlib Programming Volume 

■ DECwindows Programming Volumes 2B and 2C 

□ VMS DECwindows Xlib Routines Reference Manual, Part I 

□ VMS DECwindows Xlib Routines Reference Manual, Part II 

■ DECwindows Programming Volume 3 

□ VMS DECwindows Device Driver Manual 

□ VMS DECwindows Server Manual 

Contact your local Digital representative for information on how to order these 
documents. 
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XllforA/UX 

A/UX is a System V-based version of the UNIX operating system for the Macintosh. See 
the following Apple documents for information about the A/UX version of X: 

> Xll User's Guide for A/UX. 

■ Xll Reference for A/UX 

■ Getting Started with X Window System for A/UX 

For a complete description of A/UX manuals, as well as part numbers and ordering 
information, see the Road Map to A/UX Documentation published by Apple Computer. 

MacXfor UNIX 

The PATHWORKS for Macintosh: MacX User's Guide (this manual) is an adaptation of the 
general MacX User's Guide published by Apple Computer. The general version of the 
guide describes how to use MacX to access X clients running on UNIX machines. The 
MacX User's Guide is packaged with the MacX program from Apple. 

MacX for A/UX 

If you are interested in running MacX under A/UX, you will need the MacXfor A/UX 
Supplement to the general version of the MacX User's Guide. The supplement explains how 
to start MacX under A/UX and describes different or additional features. Ask your Apple 
representative or an authorized Apple dealer for details about obtaining MacX for A/UX. 

Usenet 

Subscribers to Usenet can join or monitor the news group, comp.windows.x, an on-line 
forum for news and discussion of the X Window System.. Ask your network administrator 
for information about Usenet. 

Road map to the MacX User's Guide 

The road map that follows shows how the parts of the MacX User's Guide fit together. 
The road map indicates that the instructions for installing MacX are located in the 
companion guide, PATHWORKS for Macintosh: Network Services User's Guide. 
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1 MacX Overview 



This chapter introduces the X Window System and gives an overview of MacX : 
Apple Computer's version of the X server. 



What is the X Window System? 



In May 1983, Project Athena and the Laboratory for Computer Science at the 
Massachusetts Institute of Technology (MIT) embarked on a project that would let 
people work with computers in an entirely new way. The goal was to design a system 
that would allow students to run microcomputer applications, such as spreadsheet and 
word-processing programs, while simultaneously running programs on different hosts 
in remote locations. The system would also have the ability to display graphics. 

With input from major computer manufacturers, the team at MIT devised an 
innovative solution in just three years. The result — the X Window System, version 10 
release 4 — was introduced in 1986. 

In January 1988, MIT formed a consortium with most of the leading computer and 
workstation companies to continue development of the X Window System and to have it 
adopted as an American National Standards Institute (ANSI) standard. In November 1988, 
the consortium distributed version 11 release 3 of the X Window System. 

The X Window System, or X for short, is a network-based graphics system designed to 
create an enhanced computing environment using the capabilities of desktop computers. 
X draws graphics, creates windows to display and run several applications 
simultaneously, and lets you access X applications over a network from different makes 
of computers without being affected by incompatible hardware or operating systems. 

X is also called a window system or windowing environment because it displays 
applications in windows on your screen, as shown in Figure 1-1. Essentially, X 
converts your screen into a lot of miniature screens in which you can perform many 
activities rather than just one at a time. You can move, resize, and stack these windows, 
as well as reduce them to icons — a way to set aside windows without closing the 
applications in them. 
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4 File Edit Remote Window 




The primary reason for using X is that it lets you access programs remotely, over a 
network. X overcomes the incompatibilities of different hardware architectures and 
operating systems, allowing different kinds of computers to communicate with each 
other. Thus the same X program can run on any make of workstation on the network, 
and you can run an application on one machine and display the results on another. The X 
Window System is a great advance for programmers because it frees them from having to 
rewrite programs in order to transfer them from one type of computer to another. 

The designers of X realized these enhanced capabilities through a design that assigns 
the major functions of X to individual components. X functions well in a network 
environment because these components are distributed between your Macintosh® and 
the remote host computers on which the client applications reside. This concept is called 
the client/server model. Knowing something about the different parts of X and how they 
work together will give you a clearer picture of what happens when you run an X 
application. The following section describes the various components of X. 
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X Window System structure 



X is composed of two separate but interrelated groups of software that communicate 
according to the X protocol. One group of programs supports clients (X applications), 
and the other controls the desktop computer on which the clients are displayed. These 
programs can work together on the same system if clients are installed on the machine 
that displays them, or they can be separated over a network if the clients are located on 
different hosts. Figure 1-2 illustrates the relationship of these different components, 
formally referred to as the client/server model. 
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As depicted in the illustration, the X server is always located on a workstation (or 
display), whereas the two application libraries — Xlib and the X toolkit — reside with the 
clients: either on different hosts or in your own computer. At first glance, this 
arrangement seems backwards to people who view workstations as the clients of a 
server, such as the file server that contains all the programs that they use. The file server 
allows multiple workstations to share the same application simultaneously. In X, 
however, the workstation contains the server so that a person can run multiple clients 
simultaneously by displaying each one in a window on the screen. In effect, the clients 
are sharing the workstation. 
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The following paragraphs briefly describe the main functions of the basic 
components of X. 

X protocol 

The X Window System protocol, or X protocol, is a graphics description language that 
the clients and the X server in your desktop computer use to exchange information. This 
protocol defines how the clients and server compose and transmit the packets of 
instructions used to draw graphic images, windows, and text, to specify colors and fonts, 
and so on. 

X server 

An X server, such as MacX, is a program that runs on your computer and controls the 
flow of information to and from the keyboard, mouse, and screen (or screens). The 
server acts as a switchboard, relaying information from clients to the appropriate 
windows on your screen and from your computer to the appropriate client. The language 
used in this information exchange is the X protocol. 

In addition to routing messages, the server performs other communications-related 
services, such as maintaining communications links with each client and interpreting 
network messages. The server also draws graphic images and windows; installs fonts; 
tracks the cursor and maintains its color, size, and shape; maintains a map of color 
values; and requests services from the operating system. 

X library 

The X library (also known as Xlib) is a library of C routines— program segments written 
in the C programming language. Each routine performs a particular task when called by a 
client program. For example, Xlib routines allow a client to communicate with a server, 
request that a window be created, draw graphics, respond to output from the keyboard 
or mouse, and so forth. Xlib routines are translated to X protocol requests before being 
transmitted to the server. 
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Window manager 

A window manager is a client application that controls the layout of windows on your 
workstation's screen(s). Window managers let you move, resize, and stack windows; 
create new windows; and shrink windows to icons. Some window managers enforce a 
layout policy, which specifies the sizes and positions allowed for windows and icons. 

X toolkit 

An X toolkit is a library of subroutines that employs several Xlib drawing routines and 
other functions to produce larger graphic objects, such as menus and scroll bars. 
Programmers use these objects, called widgets, to create the images you see on your 
desktop. Other toolkit subroutines manage and destroy widgets. A toolkit also furnishes 
tools called intrinsics, used to create new widgets. 



A brief look at how X works 

In order to display clients on your screen, you must first start up the X server. When the 
server starts up, in a standard X configuration, it creates a background, or root window, 
that covers the entire screen. Typically, your .login or .profile file will contain a command 
to start up the window manager; if it does not, you must start the manager yourself. 

Once the window manager is running, you can issue commands to run clients on 
your own machine, or you can log on to other host computers and issue remote 
commands to run clients. When you issue such a command, the client responds by 
sending X protocol packets to the X server, requesting that it draw a window of a certain 
size in a certain location. The X server interprets these requests and relays them to the 
window manager. If the window manager approves, a window appears on your screen, 
and you can use the client application. By following this procedure, you can display as 
many clients as your computer will accommodate. 
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Windows and their hierarchy 

In an X environment, windows operate according to a hierarchy, with the root window at 
the top. In traditional X systems, the root window is always visible and covers the entire 
screen. (X supports workstations with multiple screens— if you have more than one 
screen connected, a root window appears in each one.) All other windows are 
subordinate to the root window. 

Occupying the second level of the hierarchy are the top-level client windows — the 
windows that appear when you start up a client. For example, in Figure 1-1, the Clock 
and the Calculator clients are displayed in second-level windows. You can resize these 
windows, move them around, and manipulate them in other ways, according to the rules 
of the window manager. 

At the third and lower levels of the hierarchy are windows created by clients. The 
clients control these windows. In Figure 1-1, the keys on the calculator are third-level 
windows. 

♦ Window disguises Windows don't always have to look like windows. In X, a 
window is a rectangular object that is sensitive to a mouse pointer. Clients often draw tiny 
subwindows that look like menus, buttons, scroll bars, and other shapes. When the 
mouse pointer enters or the mouse is clicked in one of these subwindows, the client that 
created the window receives the feedback. ♦ 

Another important point about the window hierarchy is that higher-level windows 
impose restrictions on lower-level ones. A window is subordinate to the window that 
created it (parent window). A subordinate (child) window always remains within the 
boundaries of its parent window. Even though a child window can be larger than its 
parent, you will see only the part bounded by the dimensions of the parent window. 

The rest of this chapter describes MacX, Apple's X Window display server for a Macintosh 
running the Macintosh Operating System. 
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Introducing MacX 



The MacX application is an X server for the Macintosh. By permitting a Macintosh to run 
X applications, MacX combines the advantages of X with the advantages of the Macintosh 
computer and its easy-to-use software. For example, MacX lets you cut and paste text 
between Macintosh and X applications. MacX also offers features not included in the 
standard X environment and streamlines operations such as changing fonts and adding 
new colors. 

MacX fully conforms to the standards published in the Inter-Client Communications 
Conventions Manual (ICCCM) and to version 11, release 3 of X, with some release 4 
enhancements. 



What you get with MacX 

In addition to the X server, MacX software includes the following components: 

■ MacX Window Manager 

The MacX Window Manager allows you to create and use X windows as you would 
Macintosh windows. It supplies a selection of five window styles and lets you convert 
windows into icons. This window manager handles windows in rootless style, a style 
in which the root window is invisible. MacX provides the option to display or hide the 
root window. 

■ MacX Font Director 

The Font Director displays and sorts X and Macintosh fonts and compiles Adobe 
Bitmap Distribution Format (BDF) files into X fonts. It also permits you to assign 
aliases to long, unwieldy font names. 

■ MacX Fonts folder 

This folder contains a number of files, each of which contains a different font. For 
example, one file might contain Courier 12-point bold, and another file might contain 
Courier 14-point bold. MacX includes the entire set of DECwindows fonts as well as 
the standard set of MIT fonts. 

■ MacX Colors file 

This file contains an array of colors available for use with MacX. You can add, modify, 
or delete colors by using the MacX Color Namer. 



MacX 
Application icon 
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X with a Macintosh flair 



MacX is designed to blend in with your Macintosh working environment, adding another 
dimension to your desktop without impeding or limiting Macintosh facilities. While MacX 
is running, you can use MultiFinder® and your desk accessories. You can run Macintosh 
applications and various clients simultaneously, as shown in Figure 1-3. 




Functions such as cut, paste, save, and quit operate the same way in MacX that they 
do in most Macintosh applications. You can cut and paste text and graphics between 
Macintosh and X applications. 

MacX uses the Macintosh method for handling windows. It also gives you the option 
to use a different window manager. 

MacX supplies a variety of colors and fonts, and makes them easier to use than those 
in standard X environments. For instance, the Color Namer shows an example of each 
available color, so that you don't have to imagine what a color looks like. You can create 
and remove colors, change color names, and copy color names into X commands in 
client windows. 
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With the MacX Font Director, you can use Macintosh and X fonts interchangeably and 
assign aliases to long, cumbersome font names. The Font Director also provides a variety 
of methods for sorting fonts. 

Each time you start up MacX, it creates a settings document. The settings document 
stores the details of the working environment that you set up — every remote command 
that you create, every preference that you specify, and so forth. When you quit, MacX 
will prompt you to name and save your settings document. If you save the settings 
document, then you can return to that environment whenever you like, by double- 
clicking the document's icon. Settings documents let you customize environments for 
different hosts, clients, types of tasks, and working styles. 



What you see on the screen 

MacX displays each DECwindows™ application that you open in its own window. In 
effect, MacX converts your screen into a number of miniature screens so that you can 
perform many activities rather than just one at a time. You can move, resize, and stack 
these windows, and reduce them to icons — a convenient way to set aside windows 
without closing the applications in them. Each application can also create its own 
windows; the application controls how they are manipulated, and they must remain 
within the boundaries of the application's window. 

MacX offers two different ways to display windows: rooted and rootless. To conform 
with the traditional X environment, MacX creates a root window. The root window acts 
as a "desktop" upon which the other windows are displayed. The windows operate 
according to a hierarchy, with the root window at the top. At the second level are the 
windows that appear when a user starts up client applications. At the third level are 
windows created and controlled by the clients. (MacX actually creates two root 
windows— one for color clients and one for black-and-white clients.) 

Figure 1-4 shows a typical black-and-white MacX root window with two client 
applications open. The Calculator and Clock clients are displayed in second-level 
windows. The keys on the Calculator are third-level windows, created by the Calculator 
application. 
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Figure 1-4 MacX windows in rooted style 



By using a menu command, the MacX user can choose to hide or show the root 
window. Because the root window is at the top level of the window hierarchy, hiding the 
root window makes all of the second- and third-level windows invisible as well. 
Displaying clients in this manner, with a root window at the top of the window hierarchy, 
is known as the rooted style of operation. For more information on using a visible root 
window, see "About Root Windows" in Chapter 4. 

MacX, however, also takes advantage of the Macintosh computer's existing, sophisticated 
graphical interface. MacX can display X clients in standard Macintosh windows, 
independent of the root window. Displaying clients in this manner is known as the 
rootless style of operation. When you work in the rootless style, the top level of the 
window hierarchy comprises the windows that appear when you start up client 
applications. At the second level are windows created and controlled by the clients. 
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Figure 1-5 shows client applications open in rootless style. 




For each DECwindows application that you start, MacX offers you the choice of 
working in the rootless or rooted style. If you are familiar with the traditional X 
environment, you may be more comfortable working in the rooted style. You may also 
want to specify the rooted style if you want the convenience of hiding all of the client 
application windows by simply hiding the root window. 

Clients that you open in the rootless style are managed by the MacX Window 
Manager, which runs on your Macintosh computer. It is the MacX Window Manager that 
lets you move windows, resize them, and so on. If you open a client in the rooted style, 
the window mangement functions for that client are handled by a remote window 
manager, such as the DECwindows Window Manager. 
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Using multiple screens 

In accordance with X specifications, MacX supports single or multiple screens. You can 
use any combination of color, gray scale, or monochrome screens. Figure 1-6 illustrates a 
multiple-screen setup. 




Figure 1-6 A Macintosh with multiple screens attached 



Multiple screens on a Macintosh, however, work differently from multiple screens on 
a typical X workstation, where each screen is completely separate from the others. If you 
are familiar with using multiple screens on a Macintosh, you know that when you move a 
window halfway between two screens nothing in the middle of the window gets lost, 
despite the physical separation between the screens. The screens act as if they are 
continuous because the Macintosh Operating System joins multiple screens edge-to-edge 
into one big screen. 

To see what this arrangement looks like, open the Control Panel from the Apple 
menu (#) and click the Monitors icon. You will see a diagram similar to the one in 
Figure 1-7. The screens in the Control Panel should be arranged like the monitors on 
your desk, except with no spaces between them. 
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Figure 1-7 A Control Panel diagram of multiple screens 



Now imagine a rectangle drawn around all of the screens in your Control Panel, like 
the teal-colored one in Figure 1-7. You will notice some blank areas if the screens are 
different sizes. MacX treats the entire contents of this rectangle, including the blank 
areas, as one continuous screen on which it can display windows. That's why part of a 
window can disappear when you move it from a taller screen to a shorter one. For 
example, if you moved a window from the top of screen 3 in Figure 1-7 straight across to 
the blank area above screen 2, which is shorter, part of the window would not appear 
until you pulled it down into screen 2. 



Overview of MacX features 

This section introduces you to the functions available in the MacX menus. Besides 
supplying all the tools found in standard X products, MacX enhances many of them by 
extending their capabilities or by making them simpler to use. 
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Remote commands 



A remote command is an instruction that you send to a host computer to start an X client 
or to perform some other function in the X environment. Figure 1-8 shows the Remote 
menu, which lets you create and edit remote commands, display command output, and 
determine access control. The menu also gives a list of the remote commands in the 
currently open settings document. 



Remote 



New Command... 9€R 
Edit Command... §§E 

v"ficcess Control 3SH 

Denuer Color Session Mgr 
Sante Fe BG W Session Mgr 

Figure 1-8 The Remote menu 

To run DECwindows applications and display them on your Macintosh screen, you 
must issue a remote command to the VAX™ host computer(s) where the applications 
reside. Choosing New Command from the Remote menu brings up the Remote 
Command dialog box in which you type your command, user name, password and other 
options. Figure 1-9 shows the Remote Command dialog box. 
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[ Cancel ] 







Figure 1-9 The Remote Command dialog box 
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After entering a remote command, you have the option to execute, set, or cancel it. 
Clicking Execute or Set enters the command in the Remote Command list (which you 
display by choosing the Edit Command item in the Remote menu) and at the bottom of 
the Remote menu. Commands are listed alphabetically. Clicking the Execute button also 
causes MacX to execute the remote command. 

The next menu item, Edit Command, lets you change an existing command. Edit 
Command is dimmed if no commands exist. The Command Output submenu presents a 
list of commands that are currently running or that have command output. Choosing a 
command in the output list displays an output window that shows any information 
generated by or about the command. The checked menu command, Access Control, is a 
security precaution that prevents surreptitious access to your MacX server. For basic 
information about remote commands and step-by-step instructions, read Chapter 2, 
"Getting Started." 

For advanced information about remote commands, read Chapter 3, "Using Remote 
Commands." 

Window management 

Figure 1-10 shows the MacX Window menu. 



Show BG 111 Root Window 
Show Color Root Window 

■ Color Namer 

Figure 1-10 The Window menu 

You can use the Window menu to shrink client windows to icons, to choose a 
different style for a client window from the five shown in Figure 1-11, and to move or 
resize a window that doesn't have a title bar or size box. To learn more about these 
features, read "Using Windows in MacX" in Chapter 4. 



S&t UHmUmi Style 
Close Window 
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Choosing Iconify from the Window menu lets you shrink a client window into an 
icon in order to move it out of the way. Iconifying does not kill a client or suspend it's 
operations. Double-clicking the icon returns the client window to its normal size and 
position. 

Temporarily Adorn allows you to move and resize a window that does not have a title 
bar or a size box by temporarily converting the window to the style that has these 
elements (see the second window from the left in Figure 1-11). You have one 
opportunity to either move or resize the window, after which it reverts to its former style. 

The Close Window command changes depending on the type of window that is in 
the foreground (what is called active in the Macintosh environment). Close Window 
closes a MacX window, such as the Remote Command dialog box or the Color Namer 
dialog box, if it is frontmost. If a client window is the frontmost window, the Window 
menu displays the Kill Client command. Since this command causes an abrupt 
disconnection, read "Killing Clients and Closing Windows" in Chapter 4 before you kill 
a client. 

When windows open, their names appear in alphabetical order at the bottom of the 
Window menu. A bullet identifies the window that is active. For example, the Window 
menu on the previous page shows that the Color Namer dialog box is both active and the 
only window open. When more than one name appears in this list, you can make 
another window active by selecting its name with the mouse. 

The last two commands in the Window menu let you show or hide a black-and-white 
or color root window. When a root window is visible, the word Show changes to Hide. 
Hiding a root window also hides any client windows running in it. 



Editing commands 

The Edit menu, shown in Figure 1-12, provides the standard Macintosh Undo and editing 
commands. The menu also lets you open the Font Directory and Color Namer dialog 
boxes. The commands at the bottom of the menu let you specify certain preferences for 
how MacX works. 
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Figure 1-12 The Edit menu 

MacX lets you cut, copy, and paste text between a Macintosh application or desk 
accessory and a MacX window that contains text, such as a Remote Command dialog box 
or a DECterm™ window. Similarly, MacX allows you to cut, copy, and paste graphics in 
PICT format as well. As in any other Macintosh application, these functions are located in 
the Edit menu and perform the same way. Because clients have their own commands for 
cutting, copying, and pasting, you cannot use Macintosh commands (Command-X, 
Command-C, Command- V) in a client window. However, MacX does track when a client 
cuts or copies text and records the selection in the Clipboard. Once something is in the 
Clipboard, you can paste it into any Macintosh file or document, such as a MacWrite® 
document, for example. To paste text or graphics from a Macintosh file to a client 
window, use the client's command for pasting or inserting (not Command- V). MacX 
transfers the contents of the Clipboard to a cut/paste buffer, the equivalent of a Clipboard 
in the X world, and then to the point selected in the client document. 

The Edit menu also contains Undo and Clear, which perform their normal Macintosh 
functions. Undo undoes the last change but functions only with desk accessories. MacX 
does not otherwise support it. Clear erases a selected item without saving it to the 
Clipboard. 

See the next section for an explanation of the preference items at the end of this menu. 
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Preferences 

A list of preferences, located at the bottom of the Edit menu (shown in Figure 1-12), lets 
you select default settings for the root- window size, client window styles, passwords, 
animation, mouse movement, and arrow keys. 

Choosing either of the first two preference items displays a Rooted Screen Setup 
dialog box, which allows you to set the size of the root window. 

Normally, most people do not need to alter the default root-window preferences. 
Unless you are an experienced user of X or plan to run memory-intensive color clients on 
machines with 2 megabytes of RAM or less, you would be better off not changing the 
default root-window size. However, those who need more information should read "Root 
Window Preferences" in Chapter 4. 

Window Preferences, the next item, permits you to choose a default window style for 
client windows from the ones shown in Figure 1-11. The next time you start a client, its 
window will appear in the chosen style. One remaining choice, called Client Specified, is 
not actually a window style but lets the client indirectly influence the window style 
selected. If you choose Client Specified, MacX will convert a client's border-width request 
into one of the five window styles. See 'Window Styles" in Chapter 4 for a further 
explanation of this case. The window styles in Figure 1-11 apply only to client windows 
in rootless style. In rooted style, different window managers control the style, or 
adornment, of client windows. 

Figure 1-13 shows the dialog box that appears when you choose the last entry in the 
Edit menu, Miscellaneous Preferences. The Miscellaneous Preferences dialog box 
contains five options. Clicking the first check box saves passwords entered in Remote 
Command windows so that you don't have to retype your password every time you 
execute a remote command. The passwords are saved in the settings document and are 
encrypted to provide an extra measure of security adequate for most business needs. In 
cases where passwords aren't saved in remote commands, clicking the second check box 
will cause MacX to prompt you for these passwords when you execute such commands. 
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Figure 1-13 The Miscellaneous Preferences dialog box 

The next option — for smoother animation — should be checked if you are using 
clients that have animation. It slows down the display, however, so for other clients you 
might want to uncheck it. See Appendix A for information on this option and the one for 
enabling mouse movement. The last option lets you choose whether to use the Option 
key with the Arrow keys to do scrolling or to simulate extra mouse buttons and modifier 
keys. See "Mouse Differences," later in this chapter, for an explanation. 



Fonts 

Choosing Fonts from the Edit menu brings up the Font Director dialog box pictured in 
Figure 1-14. This window displays a list of all the fonts available for use with clients. 
These can be either X fonts (including DECwindows fonts) or Macintosh fonts, which are 
distinguished by a little icon at the beginning of the font name. The Font Director also 
allows you to create aliases as substitutes for font names. Since X and DECwindows font 
names tend to be long and unwieldy, you can create aliases that are shorter and easier to 
remember. Aliases also have a distinguishing icon. Chapter 5 provides more details on 
fonts and aliases. 
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Figure 1-14 The Font Director dialog box 



The Font Director also allows you to sort fonts in a variety of ways. In Figure 1-14, the 
field labeled View By is actually a pop-up menu containing a list of sorting methods, as 
shown in Figure 1-15. 
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Figure 1-15 The View By pop-up menu 



Simply select an item from the list and the Font Director will re-sort the fonts 
accordingly. The Font Director can also compile fonts from Adobe Bitmap Distribution 
Format (BDF). For more information about the Font Director and compiling BDF files, 
read Chapter 5, "Managing Fonts and Color." 
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Color Namer 



Choosing Color Namer from the Edit menu displays the Color Namer dialog box depicted 
in Figure 1-16. This dialog box displays a sample of every color in the MacX Colors file, 
providing you with a complete visual inventory of the colors you can use with color 
clients. Each color has a name that you can modify or copy to a command in a client 
window. You can also create new colors and remove existing colors. When you do, the 
Color Namer automatically re-sorts the colors by name, so that they remain in 
alphabetical order. See Chapter 5 for more information about using the Color Namer. 
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Figure 1-16 The Color Namer dialog box 



File menu commands 

Like the Edit menu, the File menu, shown in Figure 1-17, contains a number of 
commands that function in the normal Macintosh way. 
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Figure 1-17 The File menu 
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The New command creates a new settings document in which you can create and 
save new commands and preference settings. Open allows you to open an existing 
settings document, provided that one is not currently open. The Close command closes 
the document currently open. If the file is new, the name "Untitled" appears. Click Save 
to save your settings or Save As to save your settings and name the file. However, should 
you forget and choose Close, a standard Macintosh dialog box inquiring "Do you want to 
save your changes?" appears. Read Chapter 2 for more information about the settings 
document. Chapter 2 also explains the procedure for quitting from MacX, the last 
command in the File menu. 

Printing commands 

The Page Setup and Print Clipboard commands in the File menu (shown in Figure 1-17) 
are used for printing. Print Clipboard is dimmed unless you have copied something to the 
Clipboard. Use Command-C (36 -C) or Command-X (3§-X) to copy or cut text or graphics 
from a Macintosh application or a MacX window (such as the Color Namer). In a client 
window, use the client's method for copying and cutting. MacX intercepts these 
selections and pastes them into the Clipboard as well. Before printing, choose Page Setup 
and turn off Text and Graphics Smoothing. These options weren't designed for bit maps 
and as a result degrade the appearance of the printed graphic image. Leave Font 
Substitution on, however, as it preserves spacing better and uses a more readable font 
(Courier versus Monaco 9). Choose Print Clipboard to print. MacX prints text or PICT- 
style graphics. When printing text, MacX includes spaces, carriage returns, and line feeds, 
but omits any formatting. 



Mouse and keyboard differences 

Before proceeding further, you should know about the differences between the 
Macintosh mouse and keyboard and the standard mouse and keyboard specified for XI 1. 

Mouse differences 

Because the Macintosh uses a one-button rather than a three-button mouse, you cannot 
issue commands with the mouse as you normally would in other X environments. As an 
alternative for the missing two buttons, use the arrow keys as shown in Figure 1-18. 
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Figure 1-18 Substitute mouse buttons 



To use the arrow keys for their normal purpose, hold down the Option key before 
pressing one of them. 

+ Which mouse button? References to the mouse button in this document (for 
example, "Press the mouse button...") apply to the mouse button on the Macintosh 
mouse, which serves as the left mouse button in MacX. The other mouse buttons are 
specifically identified as the middle mouse button or the right mouse button. * 

If you would rather reverse this procedure — that is, press the Option key together 
with an arrow key to get extra mouse buttons — you can select the Option + Arrow Keys 
button in the Miscellaneous Preferences dialog box, as shown at the top of Figure 1-19. 

You'll find Miscellaneous Preferences at the end of the Edit menu. 
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Figure 1-19 The arrow keys preference option 



Keyboard differences 

The Macintosh Plus keyboard has no Control key, so you must use the Command key 
(3§) instead. As a result, you cannot use the Command key to select menu items from the 
keyboard, such as 3§-X to cut and §§-V to paste, while MacX is running. 



Substituting keys for mouse clicks 

MacX has a variety of dialog and alert boxes that it displays when you select certain 
options or need to respond to a particular event. The Remote Command dialog box shown 
in Figure 1-9 is an example. These boxes contain a collection of fields, buttons, or both, 
which you must select or click. Sometimes pressing keys on the keyboard is more 
convenient than using the mouse to click a button, choose a field, or select the contents of a 
field. For such instances, Table 1-1 lists some substitute keys and the action each performs. 
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Table 1-1 Keyboard substitutes for mouse clicks and selections 



Key(s) 



Purpose 



Y,0 

Return, Enter 
N,C 

Command-. 

Esc 

Fwd Del 

Tab 
Arrows 

Home, Page Up 
End, Page Down 



Either the Y or the key can be used to specify yes or OK in a dialog box or alert box 
that contains no text or scrollable fields. If the box has text fields, the letter is 
interpreted as text rather than as a command and is entered into the field that has the 
cursor in it. If the box has scrollable fields, the letters select a position in the field. 

Either the Return or the Enter key can be used to simulate clicking the default 
(outlined) button in any dialog box or alert box, including those with text fields. 

Either the N or the C key can be used to specify no or cancel in a dialog box or alert 
box that has no text fields. If the box has text fields, the number or letter is interpreted 
as text rather than as a command and is entered into the field that has the cursor in it. 

The Command-Period can be used to specify no or cancel in any dialog box or alert 
box, including those with text fields. 

The Escape key can be used to select the cancel button in any dialog box or alert box, 
including those with text fields. 




The Forward Delete key can be used to delete text to the right of the 
cursor. (The forward delete key appears only on extended keyboards.) 



The Tab key can be used to tab to the next text field. 

The Up, Down, Left, and Right arrow keys can be used to move the cursor and to scroll 
vertically and horizontally in text fields. Fields can contain a maximum of 255 
characters. The arrow keys will also move the cursor to a different insertion point. 

Either the Home or Page Up key can be used to scroll to the beginning of a text field or 
to the top of a list. (These keys appear only on the extended keyboard.) 

Either the End or Page Down key can be used to scroll to the end of a text field or to 
the bottom of a list. (These keys appear only on the extended keyboard.) 



♦ Using letters and numbers to scroll The Color Namer and the Font Director, two 
features described in Chapter 5, won't interpret letters or numbers as yes, no, OK, or 
cancel actions. Instead, they interpret any letters or numbers typed as scrolling 
instructions. See Chapter 5 for more information. ♦ 
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2 Getting Started 



Before reading this chapter, you should install MacX and your communications software. 
Follow the instructions in the Installation part of the PATHWORKS for Macintosh: 
Network Services User's Guide. 

This chapter gives the basic information that you need to access DECwindows 
applications with MacX. This chapter tells you how to start MacX, start a DECwindows 
Session Manager, run DECwindows applications, quit DECwindows applications, and 
quit MacX. 

Once you feel comfortable with these fundamentals, you can use the rest of this guide to 
customize your X environment and learn about more advanced features. However, 
please note that some operations and techniques, such as using fonts, require technical 
expertise. To avoid problems, consult your resident X expert when you are not sure what 
to do. 



Starting MacX 



To start MacX, double-click the MacX application icon or click the icon once and choose 
Open from the File menu. After you start MacX, your desktop should look similar to the 
one shown in Figure 2-1. You should see the four MacX menu headings in the menu bar 
at the top of your screen and, if MultiFinder is active, the MacX icon at the far right. 
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Figure 2-1 The Macintosh desktop after starting MacX under MultiFinder 

Although you don't see a window for it, MacX always opens a new settings 
document when it starts up. The settings document stores the details of the working 
environment that you set up — every remote command that you create, every 
preference that you specify, and so forth. When you quit, MacX will prompt you to 
name and save your settings document. If you save the settings document, then you 
can return to that environment whenever you like, by double-clicking the 
document's icon. 



MacX 

Application icon 



28 Chapter 2 Getting Started 



IX 



Settings documents let you customize environments for different hosts, clients, types 
of tasks, and working styles. For example, you could create an environment for doing 
Sample budgets — in which a spreadsheet client automatically opens in the middle of your screen 
and a calculator appears in the upper-right corner — and save it in a settings document 
called Budget. 



MacX settings 
document 



Making a fast exit 

If you want to exit from MacX and you haven't made any changes that you want to save, 
such as creating a remote command, simply choose Quit from the File menu or press 
Command-Q (3€-Q) and MacX will close. If you have made changes, the dialog box 
"Save changes before closing?" appears. For further information, see "Quitting MacX," 
later in this chapter. 



Starting the Session Manager 

The Session Manager provides a convenient way to enter the DECwindows 
environment. The Session Manager is a DECwindows application that lets you perform 
the following tasks: 

■ Start the DECwindows Window Manager. 

■ Access the VMS™ operating system (by using DECterm, a terminal emulator). 

■ Print the contents of a display screen. 

■ Customize your working environment. 

■ Run other DECwindows applications, such as FileView. 
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Figure 2-2 shows the Session Manager window with the Applications menu pulled 
down. After you start the Session Manager, you can run other DECwindows applications 
simply by choosing their names from the Applications menu. 

♦ Customizing the Applications menu The Session Manager is preconfigured 
to show a specific set of names in the Applications menu. If the application you want 
to use does not appear in the menu, you'll have to add the application's name to the 
menu by using the Customize menu. For instructions, see the VMS DECwindows 
User's Guide. ♦ 
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Figure 2-2 The Session Manager window with Applications menu pulled down 



To start the Session Manager from MacX, you must configure and execute a Remote 
Command dialog box. The Remote Command dialog box lets you enter a remote 
command, which is an instruction that can start an X client on a host computer. In the 
procedures that follow, the remote command is defined to start the DECwindows Session 
Manager. In the Remote Command dialog box, you'll also have to indicate the type of 
display you want for the Session Manager, enter your user name and password, and set 
other options. Finally, you must specify the host computer and a connection method. 



About connection methods 

The steps that you perform to start the Session Manager depend on the connection 
method that you use. Connection method refers to the way in which your Macintosh 
and MacX are connected to a DECwindows client and the communications protocols 
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used in the connection. (For an explanation of communications protocols, as well as 
other networking terms and concepts, see Appendix A in the Network Services User's 
Guide) 

You can connect your Macintosh to an X client using the following three methods: 

■ AppleTalk-DECnet (also known as an ADSP connection) 

■ TCP/IP 

■ DECnet 

Other connection methods- may also be available to you. The method that you use 
depends on your particular network environment. 

By choosing a connection method in the Connection Settings dialog box, you are 
really choosing a connection tool. Connection tools define the type of connection that 
is established between your Macintosh and another computer. Connection tools are one 
type of communications tool. Communications tools are pieces of software that 
manage specific communications tasks for a communications application such as MacX. 

The AppleTalk-DECnet connection method is the only method that allows you to 
execute a remote command to start an X client in the DECwindows environment. This 
section, therefore, describes how to make a connection with the AppleTalk-DECnet 
Connection Tool. 

The AppleTalk-DECnet Connection Tool establishes a connection to a 
DECwindows application through the AppleTalk/DECnet Transport Gateway. (The 
AppleTalk-DECnet Connection Tool reference module, in the Connection Tools part of 
this guide, provides information about the gateway as well as about the AppleTalk- 
DECnet Connection Tool.) 

Before configuring the Remote Command dialog box to use the AppleTalk-DECnet 
connection, you may need to select a network, and you must select a gateway through 
which to connect to the network. Proceed as follows: 

■ If your Macintosh is connected to more than one network, you must select the 
network that contains the VAX computer running the DECwindows application(s) 
that you want to use. See the next section, "Selecting a Network Connection." Then 
go on to "Selecting a Gateway." 

■ If your Macintosh is connected to only one network, you need only select a gateway 
from the Chooser. Skip to "Selecting a Gateway." 
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Selecting a network connection 

If your Macintosh is connected to more than one network, follow the procedure in this 
section to make sure that the correct network is selected. If your Macintosh is not 
connected to more than one network, you may skip this section and proceed directly to 
"Selecting a Gateway." 

If your Macintosh is connected to multiple networks, only one network can be active at a 
time. You use the Network device in the Control Panel to select the active network. 

To select a network connection: 

1 Choose Control Panel from the Apple (#) menu. 

The Control Panel window appears. 
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2 Select the Network icon from the group of icons on the left side of the 
Control Panel window. 



You may have to scroll through the list to find the Network icon. 
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Select the icon for the network connection that you want to use. 

A separate icon represents each network to which your Macintosh is connected. If you 
are attached to a LocalTalk® network, that connection is usually made through the printer 
port, and its icon is labeled Built-in. 

You may also have connections to Ethernet environments, through Ethernet cards (such 
as the Apple® EtherTalk®NB Card) installed in your Macintosh. Each icon for an Ethernet 
connection is labeled EtherTalk. If you have more than one Ethernet connection, each 
icon's label includes a number in parentheses indicating the slot into which the Ethernet 
card is installed. 
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Close the Control Panel window. 
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Selecting a gateway 

The Macintosh Operating System remembers your gateway selection for future sessions. 
After you've selected a gateway once, you only need to repeat this procedure if you want 
to select a different gateway. 

To select a gateway: 

1 Open the Chooser from the Apple (#) menu 

The Chooser window appears. 
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L Make sure that your Macintosh is physically connected to the network, and 
select the Active option for AppleTalk®, in the lower-right corner of the window. 

3 If your network is divided into zones, select the zone that contains the gateway 
that you want to use. 

The list of available zones appears in the lower-left corner of the window. 
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Select the Apple-Digital icon from the group of icons in the upper-left area of 
the Chooser window. 
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Select the gateway that you want to use from the list in the upper-right part of 
the window. 
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Close the Chooser window. 
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Configuring and executing the remote command 
dialog box 

This section tells you how to create a remote command to start the DECwindows Session 
Manager through an AppleTalk-DECnet connection. In the Remote Command dialog box, 
you also set certain options and specify the host computer and a connection method. 

To configure and execute the remote command dialog box: 
1 Choose New Command from the Remote menu or press Command-R. 




✓ Recess Control 3€H 



The New Remote Command dialog box appears. 
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Enter the command to start the Session Manager. 

Type the command run sys$ system :decw$ session in the Remote 
Command field. 



New Remote Command 



Remote Command: 

run sys$system:decw$session| 



Fill in the rest of the New Remote Command dialog box. 

Command Name: Enter an abbreviated name for your command. This name will appear 
at the bottom of the Remote menu so that you can choose it in future sessions when you 
want to execute the command. The name will also appear in the Edit Remote Commands 
dialog box and in the Command Output submenu so that you can edit the command or 
view command output. 

Display: This pop-up menu contains a list of the four types of screens on which you can 
display your remote command. (On monochrome systems, only the first two types of 
screens appear in the menu.) 
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Choose the style (rooted or rootless) in which you want to use MacX. (See "About Root 
Windows" in Chapter 4 for details.) 
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Output: Select Save or Notify from the Output pop-up menu to retain any system or error 
messages generated if the command doesn't work or gets interrupted by a problem with 
the host or the network. 
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The Notify option triggers a beep and causes a small, flashing MacX icon to appear at the 
left end of the menu bar when MacX receives output from the host. See "Creating New 
Commands" in Chapter 3 for an explanation of the other output options. 

Username: Enter the user name assigned to you by your system administrator. 

Password: Enter the password assigned to you by your system administrator. Each 
character typed appears as a dimmed, gray box for security purposes. 

Save Password: This check box should be dimmed. If not, leave it unchecked for now. 
For more information, see "Saving Passwords" in Chapter 3. 

Execute at Startup: Check this box to automatically start the Session Manager in the 
future whenever you open your MacX settings document. If you want to bypass this 
option later, hold down the Option key while MacX is starting up. After the MacX 
startup window disappears, you may release the key and no Session Manager 
window will appear. 

Host: Click the Host button to display the Connection Settings box. At the top left side of 
the box, a pop-up menu labeled Method contains a list of connection tools that allow you 
to use DECwindows applications. You should accept the AppleTalk-DECnet connection 
method, which is the default connection method for the PATHWORKS™ for Macintosh® 
version of MacX. 
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Notice that when you select a different connection tool, the lower part of the Connection 
Settings dialog box changes. Each connection tool has a different set of options for you to 
configure. 

In the field labeled Node Name, enter the node name of the VAX running the 
DECwindows applications that you want to use. Ask your system administrator if you 
don't know the node name. 

Click the OK button. 

The Connection Settings dialog box disappears. 

In the New Remote Command dialog box, click the Execute button or press the 
Return or Enter key to execute your command. 

If you didn't enter a password in the Remote Command dialog box, MacX prompts you 
with the dialog box in the following figure. 



Please enter a password to permit 
enecution of the remote command 
"SF SessionMgr". 



[( OK | [ Cancel 
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After a brief pause, MacX may display the alert box shown in the next figure. If this 
optional security measure is active, the alert appears in response to any attempt to 
connect with your MacX server. It prevents others from surreptitiously accessing MacX 
from another terminal without your knowledge or approval. 
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Because this warning has appeared at this time in response to your own remote 
command, click the OK button. 

This first alert signals a test connection that MacX sets up to make sure everything is 
working correctly. A few moments later, you'll get a second, identical alert that signals 
that the DECwindows application is establishing a permanent connection for your 
session. 

Within a few moments, the Session Manager window similar to the one shown here 
should appear on your screen. 



WO^m Session Manager: © Digital Equipment Corp. 1988, 1989. 
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Because Session Managers are usually configured to open the FileView application 
automatically, a third alert will probably appear, indicating that FileView is attempting to 
attach to your server. FileView is a graphical interface to the VMS operating system. (You 
can select other applications to start up automatically with the Session Manager by using the 
Autostart command in the Customize menu. See the DECwindows User's Guide for details.) 
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If nothing appears after a minute or so, you may have made an error typing the 
command, your user name, or your password. For other types of problems, such as 
network malfunctions, alert boxes will appear on your screen to inform you of the type 
of error. See Chapter 6, "Troubleshooting," if you need more help. 



Running DECwindows applications 

You can always start an application from the Remote Command dialog box, just as you 
started the Session Manager. However, the Session Manager and FileView provide 
simpler methods. 

As mentioned earlier, the Session Manager lets you start another DECwindows 
application by choosing its name from the Applications menu. You can use the same 
method from FileView, which contains a similar menu. Figure 2-3 shows the Session 
Manager window with the Applications menu pulled down and the Calculator 
application chosen. 
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Figure 2-3 Starting an application from the Session Manager 



In both the Session Manager and FileView, you may need to customize the 
Applications menu if the menu does not contain the names of the applications that you 
want to run. You can add names to the Applications menu by using commands in the 
Customize menu. The VMS DECwindows User's Guide gives details on customizing the 
Session Manager, FileView application, and other parts of your DECwindows 
environment. 
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You can also start applications from the DECterm terminal emulator. DECterm is a 
DECwindows application that emulates a VT320™ terminal, giving you direct, command- 
line-oriented access to the VMS operating system. To start an application, you enter 
Digital Command Language (DCL) commands in a DECterm window. 

You may find it convenient to start applications through the terminal emulator if you 
are used to interacting directly with the VMS operating system. Of course, the VMS 
operating system and DCL commands provide many other powerful capabilities. See the 
VMS User's Manual for complete information on using the DCL. 



Starting DECterm 

To start DECterm and create a terminal window, you choose DECterm from the Session 
Manager's Applications menu, as shown in Figure 2-4. 
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Figure 2-4 Starting DECterm 



Refer to the VMS DECwindows Desktop Applications Guide for more information about 
starting and using DECterm. 
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Running the DECwindows Window Manager 

When you work in the rootless style, windows are managed by the MacX Window 
Manager, which runs on your Macintosh computer. It is the MacX Window Manager that 
lets you move windows, resize them, and so on. 

If you choose to work in the rooted style, the DECwindows Window Manager, which 
runs on a VAX computer, takes over the window management functions. Thus, if you are 
working in the rooted style, you'll want to start the DECwindows Window Manager as 
described in this section. If you are working in the rootless style, you can skip this 
section. 

You start the Window Manager just as you would any other DECwindows 
application. Choose Window Manager if the name is listed in the Applications menu of 
the Session Manager or FileView. Otherwise, you'll need to issue the following command 
line from the Customize menu, from a DECterm window, or from the Remote Command 
dialog box: 

run sys$system: decw$winmgr 

When starting the Window Manager from the Remote Command dialog box, be sure 
to choose either screen 1 (B&W Rooted) or screen 3 (Color Rooted) from the Display 
pop-up menu. 



Quitting DECwindows applications 

All DECwindows applications have a Quit or Exit command available from one of their 
menus, usually the File menu. You should always close a DECwindows application by 
saving your files and then choosing the Quit or Exit command, so that you don't lose any 
of the work that you have done. If you are using DECterm, you should log out of the VMS 
operating system before you quit. 

Do not use the Kill Client command; it is designed to disconnect clients, such as most 
standard X clients, that do not have a Quit or Exit command. Using Kill Client could mean 
losing the unsaved data with which you were working. 
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Quitting MacX 

This section gives the procedure for quitting the MacX application. 
To quit MacX: 

1 Quit the DECwindows applications that you are using. 

If you're using DECterm, first log out of the VMS operating system so that you don't lose 
any work that you've done. 

2 Choose Save As from the File menu. 

The Save As dialog box appears. 
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As discussed earlier in this chapter, MacX has created a settings document to preserve 
your remote command and the rest of your X environment. Unless you save the settings 
document, MacX will discard your settings information. 

3 Name your settings document. 

The document is currently labeled Untitled. Enter another name in the highlighted field 
and either press the Return key or click the Save button. (The preceding figure shows the 
name Maiden Voyage entered in this field.) MacX creates a document icon labeled with 
the name that you entered. Later, you can click the icon and return to the same 
environment that you just created. 

4 Choose Quit from the File menu or press Command-Q to exit from MacX. 



44 Chapter 2 Getting Started 



Should you forget to save your document before quitting, MacX will display an alert box 
asking whether you want to save your changes. Click the Yes button to display the Save 
As dialog box, and fill it in as described in the preceding step. 




Saue changes before closing? 



L v«» J 

( No ] [ Cancel ) 



If DECwindows applications are still running when you quit MacX, the following alert 
box appears. 
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Since clicking OK abruptly disconnects all applications and jeopardizes any unsaved 
work, you should not quit in this way. Instead, click Cancel. Quit the DECwindows 
applications as described in the preceding section, and then quit MacX again. 



Closing a settings document without quitting MacX 

To leave the environment in which you are currently working without quitting MacX, quit 
any X clients you are using and then choose Save from the File menu. 

If you haven't previously saved your settings document, the Save As dialog box 
appears. Rename and save your untitled settings document. 

Close your settings document by choosing Close from the File menu. The MacX 
application remains open. To continue working, open an existing MacX settings 
document or create a new document by choosing New from the File menu. 
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Using Remote Commands 



This chapter describes the commands in the Remote menu and gives detailed information 
on creating, editing, and executing remote commands. It also tells you how to view 
command output. In MacX, the primary purpose of remote commands is to start a 
DECwindows application, such as a DECwindows Session Manager. 

When you create a remote command, you enter a Digital Command Language (DCL) 
command in a MacX Remote Command dialog box. Although this chapter provides 
sample commands that are likely to be useful to you, you may need to refer to the VMS 
User's Manual for details on using DCL commands and interacting with the VMS 
operating system. 



The Remote menu 



To issue commands to a remote host, you use the Remote menu, shown in Figure 3-1. 
Notice that the menu is divided into two parts by a dotted line. The area above the line 
contains MacX commands; the area below the line displays the remote commands that 
you create. You can quickly execute an existing remote command by choosing its name 
from the menu. 
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Figure 3-1 The Remote menu 

Choosing New Command from the menu causes the Remote Command dialog box to 
appear. You can use the dialog box to type a new command and execute or save it. 

Choosing Edit Command displays a list of existing commands that you can edit, 
execute, or remove. Choosing the Command Output submenu displays a list of 
commands that are currently executing. To see the output and status of a particular 
command, choose its name from the list. For more information on using the Edit 
command and the Command Output submenu, read "Editing Remote Commands" and 
"Executing Remote Commands" at the end of this chapter. 

Next in the menu is the Access Control command. It prevents individuals and 
programs from connecting to MacX without your knowledge or permission. "Security 
Features," later in this chapter, gives more information about this command. 

♦ Use remote commands sparingly Remote commands are a time-consuming and 
memory-intensive way of starting up clients. For quicker results, rather than using remote 
commands, start up a client — such as the Session Manager — that provides a more 
convenient method for starting other clients. ♦ 
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Creating new commands 



To create a new command, choose New Command from the Remote menu. The Remote 
Command dialog box appears. As shown in Figure 3-2, this dialog box contains a number 
of text fields and pop-up menus. If you have not previously edited a command, the fields 
will be blank. Otherwise, they will contain information from the last command that you 
edited. 
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Figure 3-2 The Remote Command dialog box 
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Text fields in any MacX dialog box or window hold up to 255 characters. In addition, 
all text fields scroll up and down and from left to right. To scroll through them, drag with 
the mouse or use the arrow keys. (You can use certain keys as substitutes for mouse 
clicks; see Table 1-1 in Chapter 1.) 

An explanation of each field and menu command follows. 

■ Remote Command 

This field scrolls so that you can enter a lengthy command or more than one 
command. Type the DCL command(s) the way you normally would, using the syntax 
given in the VMS User's Manual. 

■ Command Name 

Assign a command name for the command that you're creating, so that you can 
choose it later from the Edit Command or Command Output submenus. 
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■ Display 

The Display pop-up menu contains a list of four types of screens on which your 
application can be displayed. (The pop-up menu lists only two types of screens if 
your system does not support color.) 
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The screen number (0 through 3) preceding each screen type represents a style 
(rooted or rootless) and a type of screen (color or black and white). In the previous 
illustration, the display chosen is number zero (0), which specifies a black-and-white 
screen in which the root window does not appear (rootless). MacX will display the 
client window on the largest video monitor that fits the screen type selected. 

♦ For TCP/IP connections If you specify an IP address in your command, you 
must append a display station and screen number to the address. The display station 
number for a Macintosh computer is always zero. See the next section, "Specifying 
Screen Numbers," for a complete explanation and a table of screen numbers. ♦ 



■ Output 

The Output pop-up menu allows you to choose from among four ways to be 
notified of output generated by your command when it is executed. Unless you 
choose the Discard option, MacX will put this output in the command's Output 
window as it arrives. 
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Notify: Choosing Notify causes your Macintosh to beep and display a small, blinking 
MacX icon at the left end of the menu bar when command output arrives. 

f * File Edit 

To cancel the notification and see the command output, choose the command name 
(or names) marked with a diamond from the Command Output menu. A Macintosh 
window displaying the output appears, as shown in the following figure. Simply click 
the close box to close the window. 
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Pop Up: Choosing Pop Up causes the Output window to automatically appear on the 
screen when command output arrives. If you are using MultiFinder and MacX is in the 
background, the Output window also appears in the background, so if you don't see 
it pop up, it might be concealed behind a foreground window. 

Save: If you want to save command output but not be notified, choose Save. When 
you want to see the output, choose the command name from the Remote menu. 

Discard: Choose Discard if you don't want to be notified of or save command 
output. This option is useful when you expect the output to be a process ID number 
or similar system information that does not interest you. 
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■ Username 

Enter the user name assigned to you on the host that will be receiving your 
command. 

■ Password and Save Password 

Enter the password assigned to you on the host that will be receiving your command. 
For security purposes, each character that you type appears as a gray box. 

If you have chosen "Save Passwords in Settings Document" in the Miscellaneous 
Preferences dialog box, the Save Password check box in the Remote Command dialog 
box will be activated. (See "Saving Passwords," later in this chapter, for instructions 
on setting this preference.) Check the Save Password box if you want to save your 
password for this command in the settings document. When you execute the 
command, MacX automatically sends the password to the host. MacX encrypts all 
passwords in the settings document, thus ensuring a measure of security suitable for 
most business purposes. However, be careful not to give away copies of settings 
documents that contain saved passwords, because the recipients will gain 
unauthorized access to the corresponding host accounts. 

If you don't check the Save Password check box, the Password field will always be 
empty and you will have to enter your password every time you execute the 
command. In the latter case, MacX displays a Password dialog box so that you can 
enter your password — as long as the "Prompt for Usernames and Passwords" option 
is checked in the Miscellaneous Preferences dialog box. If this option is not checked, 
MacX sends an empty password to the host, causing an error if the host requires a 
password. See "Saving Passwords," later in this chapter, for more information about 
this option. 

■ Execute at Startup 

Check this box if you want your command to execute automatically when you open 
the settings document in which it is saved. This option takes effect the next time you 
open the document. To temporarily override this option when you open the settings 
document, hold down the Option key until the pointer changes from a wristwatch to 
an arrow. 
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■ Host 

Click this button to display the Connection Settings dialog box illustrated in the 
following figure. At the upper-left side of the dialog box, the pop-up menu labeled 
Method contains a list of connection tools that allow you to communicate with hosts. 
Choose a tool that can establish a connection with the VAX computer to which you 
intend to send your remote command. If you don't know which connection method 
to select, contact the system administrator who maintains the host to which you want 
to connect. 
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MacX dims any connection tools in the Method pop-up menu that cannot establish 
duplex, reliable byte-stream connections. This does not imply that all of the 
remaining, undimmed connection tools will work in every case, however. The host 
receiving the remote command must support the protocol for the connection tool 
you've chosen. 

♦ MacTCP Tool Before issuing a remote command that specifies MacTCP® as the 
connection method, contact your system administrator or consult your host 
documentation to verify whether an entry identifying your Macintosh needs to be 
recorded on the host. (For UNIX hosts, this entry is often recorded in the /etc/hosts 
file.) In some cases, without this entry, the host will refuse to establish a connection 
with your Macintosh, yet it will not be able to send you an error message. ♦ 
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In the preceding figure, the connection method chosen is AppleTalk-DECnet. The 
AppleTalk-DECnet Connection Tool lets MacX connect to DECwindows clients 
through the AppleTalk/DECnet Transport Gateway. When you choose a different 
connection tool, different settings appear in the lower part of the connection settings 
option. That's because each connection tool has a different way of selecting hosts, 
and requires different settings information. 

For example, when you choose AppleTalk-DECnet from the Method pop-up menu, 
the dialog box displays the Object Description and Node Name fields. MacX fills in 
the Object Description field, so you need only supply the name of the VAX node to 
which you want to connect. (If you don't know what to enter in the Node Name field, 
ask your system administrator.) For information about the connection settings for 
each connection tool, see the reference module for the tool in the Connection Tools 
Reference part of this binder. 

■ Action buttons 

Clicking any of these buttons on the right side of the Remote Command dialog box 
causes MacX to do the following: 

Execute: Enters the command in the Remote Commands list (which you display by 
choosing the Edit Commands item in the Remote menu), enters the command at the 
bottom of the Remote menu, executes the command, and closes the Remote 
Command dialog box. 

Set: Enters the command in the Remote Commands list, enters the command at the 
bottom of the Remote menu, and closes the Remote Command dialog box. 

Cancel: Closes the Remote Command dialog box without entering the command in 
the Remote Commands list or Remote menu. 

When executing commands, MacX may display an alert box inquiring whether you want 
to permit a connection by a new X client. See "Security Features," later in this chapter, for 
an explanation. 
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Specifying screen numbers 



As explained in Chapter 1, MacX supports both traditional rooted X client windows and 
Macintosh-style rootless windows. In addition, MacX supports both monochrome and 
color screens. (To use MacX in color, you must have a Macintosh computer with Color 
QuickDraw™.) Four combinations of screen characteristics are possible. Each 
combination is referred to as a screen, and the screens are numbered through 3, as 
shown in Table 3-1. 

Table 3-1 Screen numbers 
Screen number Description 

Monochrome screen, rootless style 

1 Monochrome screen, rooted style 

2 Color screen, rootless style 

3 Color screen, rooted style 



♦ Noncolor machines Machines that don't have Color QuickDraw— for example, the 
Macintosh Plus and Macintosh SE — do not support screen numbers 2 and 3. ♦ 

When starting a client from the Remote Command dialog box, you specify screen 
type by selecting the screen number from the Display pop-up menu. (See "Creating New 
Commands," earlier in this chapter.) 

When starting a client from a terminal emulator such as DECterm, you may specify 
the screen by typing the following command (substituting n with the screen number): 

$ SET DISPLAY/SCREEN=W. 

To specify the screen type when starting a client from the Applications menu of the 
Session Manager or File View application, you must first configure the application (by 
using the Customize menu) to prompt you for the screen number when starting a client. 
(See your DECwindows documentation for information on customizing the Session 
Manager or FileView applications.) 
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♦ Screen and monitors In traditional X environments (which support only rooted 
client windows), screen numbers correspond directly to video display devices (monitors). 
The Macintosh environment, however, presents a unique situation. When you connect 
more than one monitor to a Macintosh computer, the Macintosh desktop traverses the 
monitors as if the desktop were one large area, with each individual monitor providing a 
view of only part of the larger desktop. In the following figure, the teal-colored box 
indicates the area of the virtual display. 




In the Macintosh world, therefore, there is no direct relation between physical display 
devices and screen numbers. Screen numbers refer to the type of window (rooted or 
rootless, color or monochrome). See "How Windows are Positioned" in Chapter 4 for 
more information about how windows are positioned. ♦ 



Security features 

Through passwords and the Access Control command, MacX protects itself and your 
accounts on remote hosts from unauthorized or surreptitious access. Learning about 
these features and taking some simple precautions will, in most cases, afford you more 
than adequate protection. 
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Saving passwords 



If you would rather not type your password every time you issue a remote command, 
you can have MacX save them in the settings document. To save passwords, choose 
Miscellaneous Preferences from the Edit menu. When the Miscellaneous Preferences 
dialog box appears (as shown in Figure 3-3), click the "Save Passwords in Settings 
Document" check box and click the OK button. The corresponding Save Password check 
box in every Remote Command dialog box will be activated so that you can check it. If 
any Remote Command dialog boxes are open when you set this preference, MacX will 
also check their Save Password check boxes. 



Miscellaneous Preferences 
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Figure 3-3 The Miscellaneous Preferences dialog box 

MacX encrypts all passwords in the settings document, providing a level of security 
sufficient for the needs of most businesses. Taking additional precautions to protect 
secret or sensitive information, however, is a wise practice. 

Important Be careful not to give away copies of settings documents that contain saved 
passwords, because the recipients will gain unauthorized access to the host accounts 
protected by those passwords. A 

Unless you do not need passwords for one or more of the hosts you log in to, you 
should also check the second check box in the Miscellaneous Preferences dialog box, 
"Prompt for Usernames and Passwords." This option ensures that MacX will prompt you 
for a password if you execute a remote command that has a blank password field. 
Selecting this option is especially important if you do not save passwords in your remote 
commands, because it will circumvent log-in failures on hosts that require you to have a 
password. 
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Access Control 



Access Control prevents a person or program from connecting to MacX without your 
knowledge or approval. This security feature is active when a check mark appears next 
to its name in the Remote menu. Simply choose the Access Control command from the 
menu to remove the check mark and turn this feature off. Pressing Command-H also 
turns Access Control on or off. 

When activated, Access Control displays the alert box shown in Figure 3-4 whenever 
an X client attempts to connect to your server. Access Control also displays the alert box 
when you execute remote commands. If this warning appears just after you have issued a 
command to start a client, click OK. Otherwise, take whatever precautions you think 
necessary. 
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Figure 3-4 The Access Control alert box 



Editing remote commands 

The Remote menu provides two ways to edit existing commands: 

■ Hold down the Option key while choosing a command name from the bottom of the 
Remote menu. This method is the quickest. 

■ Choose Edit Command from the Remote menu. 

When you choose Edit Command from the Remote menu, MacX displays the dialog 
box shown in Figure 3-5. The list at the left side of the dialog box contains the names of 
the remote commands that you have created. To edit a command, simply double-click its 
name in the list. 
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You can also select a command name and click one of the buttons on the right to edit, 
remove, or execute that command. When you click the Edit button, the dialog box for the 
selected command appears and you can edit or execute it. When you click the New 
button, MacX displays either a blank Remote Command dialog box, in which you can 
enter a command, or the Remote Command dialog box with a copy of the last command 
edited, which you can modify. 
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Figure 3-5 The Edit Command dialog box 



Executing remote commands 

The names of the remote commands that you have created are listed at the bottom of the 
Remote menu, below the dashed line. For example, the Remote menu in Figure 3-6 
contains three remote commands. Choosing a name from this list automatically executes 
the command without displaying its Remote Command dialog box. 

You can also execute a command from the Remote Command dialog box, described 
in the preceding section. Select the command from the list at the left side of the dialog 
box and click the Execute button. 

The next section describes how to display the output of a command that is executing. 
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Viewing a command's output 



The Output window displays information generated by a command (or about a 
command) while the command is executing. To open the Output window, select a 
command name from the Command Output submenu, shown in Figure 3-6. The 
submenu lists the command names in the order of command execution, so that the name 
of the most recently executed command appears at the top of the list. 
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Figure 3-6 An example of the Command Output submenu 



If you have chosen to discard command output (by selecting the Discard option in 
the Remote Command dialog box), the Output window will appear, but it will be empty. 

To make the Output window appear as soon as the command or the host executing 
the command generates output, select the Pop Up option in the Remote Command dialog 
box. As long as MacX is in the foreground, the Output window appears in front of any 
other windows on your screen. MacX is always in the foreground unless you are running 
MultiFinder and working in a different application. 

In the Command Output submenu, a symbol may precede some of the command 
names. These symbols indicate whether an Output window contains new information or 
information you have already read, as explained in Table 3-2. The absence of a symbol 
means that the window contains no command output. 
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Table 3-2 Command Output submenu symbols 



Symbol Meaning 

O Output window contains unread command output. 

*/ Output window contains output that you have already read. 

blank Output window contains no command output. 



Because you can issue the same remote command more than once — for instance, you 
could issue DECterm on Santa Fe two times and have two DECterm windows on your 
screen— these symbols help you keep track of which command output applies to which 
client window. 

Figure 3-7 shows an example Output window. The name of the host on which the 
command is running appears on the left, in this case Santa Fe. A word indicating the 
status of the command appears in the middle, in parentheses: either Opening, Running, 
or Exited. 
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Figure 3-7 An example Output window 
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Clicking the Change Settings button on the right lets you change the output status of 
your command. 
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Figure 3-8 The Change Settings dialog box 



The Output pop-up menu is like the one in the Remote Command dialog box— the 
menu lets you choose how MacX notifies you of command output. In the Save Lines field, 
you can enter the number of lines of command output that you want to save, up to a 
maximum of 5,000 lines. The Output window will contain no more than the number of 
lines that you specify here. MacX discards any additional output by erasing from the 
beginning so that the most recent command output is retained. 

Clicking either of the two buttons on the right will close the Change Settings dialog 
box. Click OK to save your changes and close the dialog box. Click Cancel to close the 
dialog box without saving your changes. 
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4 Working With Windows 



This chapter describes the commands in the MacX Window menu and explains how to 
position, move, and size rootless- and rooted-style client windows. It explains how to 
convert these windows to icons (called iconifying), how to restore icons to windows, and 
how to close the windows. This chapter also discusses working with a visible root 
window. For a brief introduction to the rooted and rootless styles, see Chapter 1. 

When you use MacX, the X client applications can run in windows that look and act like 
Macintosh windows. If you're familiar with the Macintosh computer, you already know a 
lot about using windows, and you may not need to read the entire chapter. However, 
MacX provides several unique features that you may want to read about, such as a 
selection of five different window styles and the ability to set aside windows by shrinking 
them to icons. 



The Window menu 



To work with windows, you use the Window menu, shown in Figure 4-1. With the 
exception of the Show B&W Root Window and Show Color Root Window commands, all 
of the commands on this menu are dimmed until you have an active client window on 
your screen. The menu in Figure 4-1 shows one active client, Clock. For instructions on 
starting up a client, consult Chapter 2, "Getting Started," or Chapter 3, "Using Remote 
Commands." 
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Figure 4-1 The Window menu 

MacX lists the titles of open windows in alphabetical order at the bottom of the 
Window menu, below the second dotted line. The menu lists rootless client windows and 
MacX windows such as the Color Namer dialog box. If you are working with a visible 
root window, its title also appears in this list, but those of its client windows do not 
appear, as they are under the control of a different window manager. 

MacX lets you have more than one window with the same title open at the same time. 
To distinguish each of these windows, MacX appends a number to its title. The first time 
that you start up a client, MacX appends no number to its title; however, if a duplicate of 
that window title appears, MacX adds a (1) to the original client window's title and a (2) 
to the duplicate window's title. Once issued, these numbers remain in the menu even 
when the original window is closed. In Figure 4-1, the title Clock (2) indicates that a 
second Clock is running. The absence of a Clock (1) title indicates that the first Clock has 
ceased operating. The bullet preceding Clock (2) means that this window is active, or 
frontmost. 
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How windows are positioned 



The position in which a DECwindows client window appears when you open it is preset. 
Usually the client window appears approximately in the middle of the screen. 
Occasionally, in the preset position only part of the window might be visible, or the 
window might not be visible at all. This situation might occur if you have more than one 
monitor connected to your Macintosh. 

In the Macintosh environment, the desktop extends across all monitors connected to 
the same workstation. Because of the different sizes of monitors and the ways in which 
they can be positioned relative to one another (using the Monitors utility in the Control 
Panel), the Macintosh desktop can have portions that are not visible. Figure 4-2 shows 
two monitors; the teal-colored box indicates the Macintosh desktop. 




Figure 4-2 Multiple monitors and the Macintosh desktop 

When DECwindows attempts to position a window in the nonvisible part of the 
desktop, the MacX Window Manager takes over and places the window near the 
desktop's point of origin (the upper-left corner). If more than one window needs to be 
placed, MacX positions the windows in a cascading sequence. MacX automatically places 
a window on the largest monitor best-suited to display it; for example it puts a color 
window on the largest color monitor available. 

For information on moving windows yourself, see "Moving and Sizing Windows," 
later in this chapter. 



How windows are positioned 65 



Using windows in MacX 

This section describes techniques for using both rootless- and rooted-style client 
windows. You can start a client in either rootless or rooted style, and you may have both 
styles of client windows on your screen at the same time. Client windows that you open 
in rootless style are controlled by the MacX Window Manager. Those that you open in 
rooted style are controlled by remote window managers, such as the DECwindows 
Window Manager. For more information about working in rooted style with a visible root 
window, see "About Root Windows," later in this chapter. 



Making windows active 

When you are working with rootless-style clients, you can make a window active in one 
of two ways: 

■ Select its title from the Window menu. 

■ If the window is already on the screen, click its title bar. 

Avoid clicking in a client window to make it active. Taking this precaution prevents 
the client from receiving the mouse click and performing some action that you don't 
expect or don't want. 

An active window in rootless style has keyboard input focus and colormap focus. 

These X terms simply mean that the client in the active window receives characters typed 
from the keyboard and controls the colors displayed on your screen. 

When you are working with rooted-style clients, the method for making a window active 
or assigning input focus depends on the window manager that you are using. Again, 
avoid clicking in a client window to make it active, as the mouse click may have an 
unexpected result. 

In the Window menu, a bullet in front of a window's title indicates that the window is 
currently frontmost (or active). (See Figure 4-1.) 
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Styling and manipulating windows 



Although MacX allows you to treat rootless client windows like regular Macintosh 
windows, MacX has no control over windows that open within a client window. 
According to X protocol convention, these subordinate windows are controlled by the 
client itself— MacX simply relays the information to your screen. 

On the other hand, the client and the host on which it runs have no control over the 
type of window that MacX creates for the client. They can make requests, called hints, 
but the MacX Window Manager, guided by your preferences, determines what is possible 
when placing windows on the screen. 



Window styles 

When you open a rootless client, it appears in a Macintosh-style window. This window 
style includes a title bar across the top of the window and a size box in the lower-right 
corner. You can change the window style by following these steps: 

1. Bring to the front the window that you want to restyle. 

2. Choose Set Window Style from the Window menu to display the five window styles. 

The style currently in effect will have a check mark next to it. Choose the style that 
you want. Figure 4-3 shows the five window styles. 
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Figure 4-3 Styles for rootless client windows 



Remember that a title bar lets you move a window, and a size box lets you resize a 
window. If you select a window style without a title bar or a size box, you can move or 
resize the window by choosing Temporarily Adorn from the Window menu. (You can 
also move a rootless window by holding down the Option key and dragging the 
window.) For more information, see "Moving and Sizing Windows," later in this chapter. 
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Setting a default window style 

You can set a default window style for rootless-style client windows by following 
these steps: 

1. Choose Window Preferences from the Edit menu to open the Window Preferences 
dialog box. 

2. Choose a style from the Default Window Style pop-up menu. 

Figure 4-4 shows the Default Window Style pop-up menu. (The window styles are 
illustrated in Figure 4-3.) The default window style that you choose takes effect the next 
time you start a rootless-style client. 
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Figure 4-4 The Default Window Style pop-up menu 



The last item in the Default Window Style menu, Client Specified, allows MacX to 
convert client border- width hints into one of the five MacX window styles. If your client 
does not provide a way to set border widths, then choose one of the other options. 

Moving and sizing windows 

Before moving or sizing a rootless client window, make sure that it is active (in the 
foreground). If the window has a title bar and size box, you can use them to move and 
size the window as you would any Macintosh window. 
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If the window has no title bar or size box, you can use one of the following techniques: 

■ You can use the Temporarily Adorn command to move or resize a window. Make 
sure that the window is active. Choose Temporarily Adorn from the Window menu. 
Your window acquires a temporary title bar and size box, giving you one opportunity 
to move or size it like any Macintosh window. When you release the mouse button 
after moving or sizing the Vindow, the window reverts to its former style. If you 
aren't satisfied with its new location or size, choose Temporarily Adorn again. 

■ You can use the Option key to move a window. Move the mouse pointer into the 
window. Hold down the Option key while you drag the window to its new position. 
Pressing the Option key changes the pointer to this icon : 



♦ Stacking windows MacX permits you to stack client windows and maintains the 
contents of windows concealed in the stack so that they reappear as you left them. In other 
words, MacX refreshes the window's contents when you uncover it so that you don't have 
to wait for a client to refresh the window, which would take longer. ♦ 

MacX allows you to move and resize a root window displayed on your screen just as you 
would a client window, because this so-called root window is actually a Macintosh 
window. For more information, see "About Root Windows," later in this chapter. 



Converting windows to icons 

When client windows get in your way, you can clear a space in two different ways. You 
can move the windows, or you can iconify them — that is, convert them into icons on 
your screen. The client can determine what the icon looks like, but if it doesn't specify 
anything, MacX displays a miniature Macintosh window. 

Client window 
icon 
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You can move an iconified window with the mouse pointer, just as you would any 
icon on your desktop. You can change the icon back to a window by double-clicking it 
or by clicking it and choosing Uniconify from the Window menu. 

MacX provides two ways to iconify a client window: 

■ Click in the window to make it active and choose Iconify from the Window menu. 

■ Click in the window to make it active and press Command-I. 

While the window is iconified, any commands, calculations, or other processes 
currently operating will continue to execute. When you double-click the icon to restore 
the window to its original size and appearance, the client redraws the contents of the 
window. 



Killing clients and closing windows 

Close Window and Kill Client are two commands that appear in the same location in the 
Window menu, depending on what type of window is active. 

When MacX first starts up, before any windows have opened, the Window menu 
displays a dimmed Close Window command. When a MacX window becomes active, 
choosing Close Window closes the window. Using this command is an alternative to 
clicking the window's close box or Cancel button. 

The Kill Client command appears only when a rootless client window is active. It is 
designed to disconnect clients that provide no way to issue commands to them directly. It 
is also useful to programmers who want to stop a runaway program. However, Kill Client 
is not the preferred way to close a DECterm or other terminal emulator window because 
it causes an abrupt disconnection. Any unsaved data in the window would probably be 
lost unless the host has some way of retaining it. 

A Important DECwindows applications have a Quit or Exit command available from one 
of their menus. It is better to use one of these commands to stop an application than to 
disconnect by using the Kill Client command. A 
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Fortunately, when you choose Kill Client, MacX does not immediately execute the 
command. An alert box appears first, inquiring whether you really want to kill the client. 
(See Figure 4-5.) In addition, the client window displays a moving, dashed outline so that 
you can clearly see which client will be killed. 



[[ OK ]] [ Cancel ) 

Figure 4-5 The Kill Client warning 

Note that clicking the close box at the left end of a client window's title bar is 
equivalent to choosing Kill Client. 



MacX creates a visible root window if one of your clients requests one. In addition, you 
can show or hide the black-and-white or color root window at any time by choosing a 
command from the Window menu. Figure 4-6 shows what your desktop looks like with 
the root window visible, assuming that your Macintosh has just one screen attached. 
Usually the root window covers the entire screen when it first appears, although you can 
set a preference to change its size. 
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About root windows 
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You'll notice that the window in Figure 4-6 has a size box in the lower-right corner. 
Though labeled root, this window is actually a Macintosh window that reveals all or part 
of an off-screen bitmap — a virtual root window stored in memory. This arrangement 
enables you to manipulate the root-viewing window without disturbing clients running in 
the underlying virtual root window. 

Figure 4-7 illustrates this concept. Notice that the root-viewing window displays part 
of a larger bitmap on which three clients are running. In this case, you see parts of the 
Clock, Calculator, and DECterm application windows. Scrolling reveals other parts of the 
client windows. 

Naturally, the root-viewing window can be smaller, but never larger, than the 
dimensions of the virtual root window. When it is smaller, the scroll bars become active 
so that you can scroll through the entire root window. 

Alternatively, you can use the hand cursor for faster scrolling: Change the pointer to a 
hand icon by holding down the Option and Command keys. Now position the 
pointer in the root-view window, hold down the mouse button, and move the mouse to 
change your view of the root window. 
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Figure 4-7 Viewing the off-screen bitmap 

In traditional X implementations, the root window never moves or changes size, so 
clients are not designed to accommodate such changes. Accordingly, MacX will not let 
you resize the virtual root window while any clients — whether rooted or rootless — are 
running. For more information on resizing the virtual root window, read "Root Window 
Preferences," later in this chapter. 



Starting rooted clients 

Before you can move and resize rooted client windows, you'll need to start a remote 
window manager such as the DECwindows Window Manager. (You can't use the MacX 
Window Manager in a root window because it controls only rootless windows.) Although 
it's not necessary to start a window manager before starting a client in rooted style, it's 
usually convenient to do so. 
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You start the DECwindows Window Manager just as you do any other 
DECwindows application. For more information, see "Running DECwindows 
Applications" in Chapter 2. 

Because the root window covers all or part of your desktop, you might find that it 
occasionally gets in the way of something else that you want to see. If this situation 
occurs, you can always hide the root window, even with clients running in it, as 
described in the next section. 

♦ Trouble starting color clients? Some color clients, such as DECwrite, require a lot 
of memory to run. If MacX tells you that it does not have enough memory to execute a 
command or warns you that memory is running low, you should allocate MacX a larger 
block of memory. See "Memory-Related Problems" in Chapter 6 for instructions. ♦ 



Showing and hiding the root window 

MacX does not allow you to iconify a visible root window, but it does give you a way to 
make it disappear for as long as you like, even when it is displaying client windows. By 
choosing one of two commands in the Window menu, you can hide the black-and-white 
or color root window. When you hide the root window, the command in the Window 
menu changes from Hide to Show so that you can make the root window reappear at a 
later time. Figure 4-1 illustrates these two commands. 



Root window preferences 

The B&W and Color Root Preferences commands, located at the end of the Edit menu, 
allow you to modify the default settings for a monochrome or color root window, 
respectively. When you select either of these commands, a Rooted Screen Setup dialog 
box appears. Figure 4-8 shows the monochrome version; the format for the color root 
window preference is the same. 

Both preferences commands let you change the size of the virtual root window 
stored in memory by using your mouse to drag the small, black square in the setup 
dialog box. The setup dialog box also displays an outline of the screens attached to 
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Virtual root 
window 



Setup window 



your Macintosh. These outlines show you how big a root window you are creating. For 
example, in Figure 4-8, the setup dialog box shows an outline for one large and one 
small screen. The virtual root window is slightly smaller than the large screen. 



BG III Rooted Screen Setup 




Outline of screens 



Drag here to resize 
root window. 



Figure 4-8 The B&W Rooted Screen Setup dialog box 

You shouldn't attempt to resize a root window when clients — rooted or rootless — are 
running. If you do, MacX displays the alert box shown in Figure 4-9. 



Resizing uirtual screens requires that 
all actiue clients be killed! 



• If you want the size changes to take effect 
the newt time this MacK document is opened, 
select "NeHt Time." 

• If immediate resizing is what you want 
(killing all actiue clients), select "Immediate." 

• To discard the size changes you made, 
select "Cancel." 



Newt Time 



Immediate 



Cancel 



Figure 4-9 The root window warning message 



You can defer your changes until later, or you can discard them altogether if you 
would rather not kill your clients in order to resize the root window immediately. 
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5 Managing Fonts and Color 



This chapter describes in detail the Font Director and summarizes the X convention 
for specifying font names. It also tells you how to use the Color Namer. 

Programmers who want to create fonts should refer to Appendix D, which contains 
the X Logical Font Description Conventions, Standard VI. 2. For those interested in 
compiling fonts from Adobe Bitmap Distribution Format files, Appendix C provides 
the Bitmap Distribution Format 2.1 standard for your reference. 

Although most of the color and font features are easy to use, the procedures for 
compiling fonts and creating new fonts can be complicated unless you have an 
understanding of the X font standards and some programming experience. If you 
don't have this background, consult with someone who does before attempting 
to compile or create fonts. 



Using fonts in MacX 



Fonts are implemented in MacX by means of three basic components designed for 
convenience and efficiency: a MacX Fonts folder, the Font Directory file, and the Font 
Director. The MacX Fonts folder holds the X font files, the Font Directory file contains a 
list of these fonts, and the Font Director lets you view and use the fonts. 



The MacX Fonts folder 



X font file 




Font Directory 



The MacX Fonts folder holds files that contain the standard set of X fonts. These files are 
organized by font family in subfolders labeled Times, Helvetica, and so forth. Each file 
contains one variation of a font. For example, one file contains Helvetica 18-point bold, a 
variation of the Helvetica font family. 

MacX stores a list of these fonts in the Font Directory file, also located in the MacX 
Fonts folder. Because the font names in this file must conform to the format specified in 
the X Logical Font Description Conventions, they are too long to serve as filenames. 
Consequently, files in the Font folder have shorter names like helvB12. 



♦ DECwindows fonts In addition to the standard set of MIT X fonts, the 
MacX supplied with PATHWORKS for Macintosh includes the full set of 
DECwindows fonts. ♦ 



The purpose of the Font Directory file is to supply the Font Director with a current list 
of X fonts, any Macintosh fonts you have chosen to use in MacX, and any font aliases that 
you have created to act as substitutes for font names or other font aliases. MacX updates 
this file every time you start up a settings document or click the Update Font Directory 
button in the Font Director dialog box. Turning on the RAM cache in the Control Panel 
speeds the updating process significantly. 

The MacX Fonts folder belongs either in your System Folder or in the same folder 
as your MacX application. To avoid complications, keep just one MacX Fonts folder on 
your disk. 
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The Font Director 



The Font Director eliminates many of the time-consuming aspects of dealing with fonts in 
a conventional X environment. To see what a font looks like, you do not have to run font 
clients or type commands with long, cryptic font names in them. Instead, you can display 
the Font Director dialog box (shown in Figure 5-1), click a font name, and see a sample 
of the typeface. 

In addition to viewing fonts, you can sort fonts in a variety of ways, assign aliases to 
font names, and compile fonts from Bitmap Distribution Format (BDF) files in a 
straightforward manner by clicking buttons in the Font Director dialog box. 

To use the Font Director, choose Fonts from the Edit menu or press Command-F on 
the keyboard. 
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Figure 5-1 The Font Director dialog box 



The list of fonts in the Font Director dialog box includes all the fonts in the MacX 
Fonts folder, any Macintosh fonts that you have added, and any X font aliases that you 
have created. An icon precedes each item in the list to indicate whether it is an X font, a 
Macintosh font, or an X font alias, as shown in Figure 5-2. 

IS) it ! 

X font icon X font alias Macintosh font 
Figure 5-2 Font Director icons 
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To make it easier to find font names in a long list, the Font Director supports all the 
standard Macintosh scrolling methods. Besides responding to the scroll bar and arrows, 
the Font Director scrolls to the font element in the list that matches a letter, word, or 
number typed at the keyboard. The View By pop-up menu displays the font element for 
which the Font Director searches. 

For example, if the font element displayed is Family, typing s causes the Font 
Director to scroll to the first font family beginning with s. Typing Times causes the 
Font Director to scroll to the first font in the Times family. Similarly, typing a number 
produces the first font family starting with that number. However, if none of the Family 
elements begins with a number, the Font Director scrolls to the top of the list. When it 
searches, the Font Director ignores case and blank spaces but not diacritical marks. 

If the Font Director cannot open a font file, it displays cross-hatched lines in the Font 
Director dialog box instead. If the file contains a reverse-character font — one that prints 
to the left rather than to the right— the display line for the font appears blank. 

The X format for font names 

In Figure 5-1, the long strings of characters listed in the Font Director dialog box are font 
names. Font names comprise a collection of font elements or properties separated from 
each other by hyphens, a format required by the X Logical Font Description Conventions. 
A font name always begins with a hyphen in MacX because the name does not include 
the Registry element (explained in Table 5-1). A pair of hyphens in a font-name string 
indicates that a font element has been omitted, not because it is optional, but because it 
does not apply to that particular font. 

Table 5-1 summarizes the format of a font name's registry and suffix as specified by 
the X Logical Font Description Conventions. The table lists the font elements in the order 
of their appearance in the font-name string, starting from the left side. For more 
information, refer to Appendix D. 
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Table 5-1 The X logical font-name format 



Element 



Definition 



Registry 
Foundry 

Family name 
Weight name 
Slant 

Set-width name 
Add style name 
Pixel size 
Point size 
X resolution 
Y resolution 
Spacing 
Average width 
Character-set registry 
Character-set encoding 



The registration authority that owns the font (its syntax and semantics). 

The type foundry that digitized and supplied the font shape or metric 
information. 

The name of a typeface, including all its style variations, such as bold or italic. 

A name identifying a font's typographic weight — for example, bold or medium. 

A one or two-letter code indicating the posture of the font — for example, R for 
Roman, /for italic. 

One or two words designating the width of a font — for example, Normal, 
Condensed, Double Wide. 

A term that identifies additional type-style information — for example, serif, sans 
serif. If a typeface doesn't have additional style information, this field is empty. 

The number of pixels required to display a particular point size. The pixel size is 
usually equivalent to or close to the point size. 

A number representing the height of the font in tenths of a point. For example, 
8 points would be expressed as 80. 

A number representing the horizontal resolution of a font, measured in dots per 
inch (dpi). 

A number representing the vertical resolution of a font, measured in dots per 
inch (dpi). 

A letter that indicates the escapement class or pitch of a font — for example, M 
for monospacing, Pfor proportional spacing. 

A number, measured in tenths of a pixel, that represents the unweighted 
arithmetic-mean width of all characters in a font. 

A name or string of alphanumeric characters identifying the organization that 
owns a typeface character set. 

The character set used to associate each character in a font with its glyph or 
image. 
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The format for Macintosh font names 

Macintosh font names appearing in the MacX Font Director dialog box have a much 
briefer format than that described in the preceding section. The format begins with the 
Macintosh name for the font. The name is followed by a hyphen, the point size in 
decimal format, and, optionally, one or more of the following letters: 

b Bold u Underline 

s Shadow e Extend 

i Italic c Compress 

o Outline m Monospaced 

For example, the Font Director would display the font name for 18-point Geneva bold 
shadowed italic as Geneva-18bsi. 



Adding a Macintosh font to the Font Director list 

Initially, the Font Director does not list any Macintosh fonts because listing all of the 
variations in each font family would make the font-name list too long. As an 
alternative, the Font Director provides a way for you to add the Macintosh fonts that 
you frequently use. 

To add a Macintosh font to the Font Director lists: 

1 Choose Fonts from the Edit menu. 

The Font Director dialog box appears. 

2 Click the New Font button. 

When the New Font dialog box appears, the New Entry Type pop-up menu should 
display the words Macintosh Font. 
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New Entry Type: | Macintosh Font I [[ n * )] 

[ Cancel ] 

Font Family: 1 fluant Garde | 
Point Size: | flg | 1 12 

□ Bold □ Shadow □ Underline 

□ Italic □Outline □Monospace 



Choose a font family, point siie, and other font properties. 

Click the Font Family and Point Size pop-up menus to choose a font name and point size. 
Click the check boxes to select other properties, such as bold or outline. 

Click OK to add the font to the font-name list. 

In the font list, as explained earlier in this chapter, Macintosh fonts are distinguished from 
X fonts by a different icon and font-name format. The location of Macintosh fonts in the 
font list depends on the font element selected from the View By pop-up menu. However, 
when the font list is set to show all fonts, Macintosh font names usually appear after X 
font names. For more information about sorting, see "Sorting Fonts," later in this chapter. 

Assigning aliases to font names 

If you find the long X font names too cumbersome or puzzling, you can create aliases for 
them. An alias is simply another name for a font. 

To assign an alias to a font name: 

Select a font name in the Font Director dialog box and click the New Font 
button. 

The New Font Alias dialog box appears. The font name that you selected appears in the 
Target of Alias field. 
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2 Click the New Entry Type pop-up menu and choose Font Alias Name. 

3 Type any combination of words, letters, or numbers in the New Alias Name field 
and click OK. 

The Font Director inserts the alias, along with any other aliases you create, into the font- 
name list. Aliases are sorted, along with other font names, according to the font element 
that you chose from the View By pop-up menu. For more information about this process, 
see "Sorting Fonts," later in this chapter. 

Copying and pasting font names 

You can use the Copy command in the Edit menu, just as you would in any standard 
Macintosh application, to copy a font name to the Clipboard and paste it into a remote 
command or a client window. Remember to enclose multiple-word font names in 
quotation marks before executing your command. Use straight rather than curly 
quotation marks. 

Once a font name is on the Clipboard, you can also paste it into a client command or 
file by using that client's paste or insert command. For example, you could paste the font 
name into a command in a DECterm window by pressing the Left Arrow key, the 
Macintosh equivalent of the middle mouse button on a three-button mouse. 
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Removing fonts and font aliases 

The Remove button in the Font Director dialog box lets you remove an X font from the 
MacX Fonts folder. It also lets you delete font names and font aliases from the Font 
Directory file and the font-names list in the Font Director dialog box. Simply deleting a 
font name does not delete the aliases associated with it, however. 

To remove a font or alias, select its name in the Font Director dialog box and click the 
Remove button. A dialog box appears, asking whether you really want to remove the 
font. (See Figure 5-3.) Click OK to remove the font, or click Cancel to retain it. 




fire you sure you want to 
♦permanently* delete the 
selected font(s)? 



[[ OK ]| [Cancel] 
Figure 5-3 Removing a font 

♦ Can't remove cursor and fixed fonts Since MacX needs the cursor and fixed fonts 
to display cursor shapes and text, these fonts cannot be removed. ♦ 

Sortingfonts 

Figure 5-4 shows the View By pop-up menu for sorting font names as they appear in the 
Font Director dialog box. The View By menu lets you choose the element for the first- 
level (initial) sort. For example, if you choose Family, MacX first sorts the font names by 
the Family element. MacX continues the process by sorting on each of the remaining 
elements, starting with the leftmost element and moving to the right. (Because MacX font 
names do not include the Registry element, the leftmost element is Foundry.) 
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Figure 5-4 The View By pop-up menu 

The way that the sort is performed depends on whether the element chosen for the 
first-level sort is alphabetic or numeric. All elements are alphabetic with the following 
exceptions: 

■ Pixel Size 

■ Point Size 

■ X Resolution 

■ Y Resolution 

■ Average Width 

If the initial sort element is alphabetic, then the sorting on all elements is alphabetic, 
even if the element is numeric. This means that numeric elements will appear to sort out 
of order because an alphabetic sort compares the elements character-by-character. In 
comparing 8 to 10, 10 comes first because alphabetically, 1 comes before 8. The 
following example shows font names sorted initially by the Family element (an 
alphabetic element): 
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If the initial sort element is numeric, then all other numeric elements are also sorted 
numerically. Alphabetic elements continue to be sorted alphabetically. When sorted 
numerically, numeric elements appear in their proper order because the elements are 
compared as whole numbers. Thus 8 comes before 10. The same names shown above, 
sorted initially by the Pixel Size element (a numeric element), appear as follows: 
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Compiling fonts from BDF files 

The Font Director enables you to compile BDF files into fonts without quitting MacX. After 
compiling a font file, click the Update Font Directory button to update the Font Directory 
file and include the new font in the Font Director dialog box. If you do not click this 
button, the Font Directory file will not be updated until the next time you start MacX. 

To compile a font: 

1 Click the New Fonts button in the Font Director dialog box. 

When the New Entry dialog box appears, choose X Font from the New Entry Type pop- 
up menu. The layout of the box changes, as shown in the following figure. 



New Entry Type: | X Font 


] ( OK ] 
[ Cancel ) 


[ Compile a BDF File... 


) 
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2 Click the Compile a BDF File button. 

A directory dialog box appears. 
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3 Locate and open the folder containing the BDF files that you want to compile. 

4 Select the name of a BDF file and click Open, or double-click the filename. 

A message appears, advising you that the font compiler is compiling your BDF source 
file. When the box disappears, the compiled font file will be in your folder. 



The font compiler is compiling your 
BFD source file. 

Please stand by... 



5 Repeat steps 2 through 4 for as many files as you want to compile. When you 
finish, drag the files into the MacX Fonts folder. 

6 Click the Update Font Directory button on the Font Director dialog box. 

MacX updates the Font Directory file. As soon as this file is updated, the newly compiled 
fonts appear in the Font Director dialog box. 
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Using color in MacX 



Unlike other X servers, which represent colors in numeric form only, MacX offers a 
visually oriented approach to specifying colors. Traditionally, the differing amounts of 
red, green, and blue that constitute colors are expressed as sets of three numeric values. 
In MacX, these sets of numbers are stored with corresponding color names in the MacX 
Colors file. MacX converts these values into colors and displays them in a dialog box 
called the Color Namer. You can also specify a broader range of color values in MacX. 
Macintosh color values for red, green, and blue range from to 65,535, whereas MIT RGB 
values range from to 255. 

This section explains how to create, modify, and delete individual colors using the 
Color Namer. For information on displaying clients that use these colors, see "Specifying 
Screen Numbers" in Chapter 3. 



The Color Namer 

The Color Namer eliminates the chore of reproducing colors in X. Instead of having to 
visualize the color you want and experiment with numerical red, green, and blue values 
until you hit upon the correct combination, you can simply open the Color Namer dialog 
box, shown in Figure 5-5, and browse through a long list of color samples until you find 
the one you want. If the color isn't in the list, you can create a new one or modify an 
existing color. In addition, you can remove colors, change color names, and copy color 
names to client commands. 

To display the Color Namer dialog box, choose Color Namer from the Edit menu. If 
the Color Namer command is dimmed, you can't choose it. In this case, your Macintosh 
does not support Color QuickDraw, a utility that the Color Namer requires. The 
Macintosh Plus, Macintosh SE, and Macintosh Portable computers do not support Color 
QuickDraw, so the Color Namer won't work on these computers. 
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Figure 5-5 The Color Namer dialog box 



Sorting, scrolling, saving, and canceling 

Sorting color names Any time you make a change that adds, removes, or modifies 
color names, the Color Namer re-sorts the color list alphabetically. The sorting method 
used ignores case and blank spaces. Any numbers at the end of a color name are sorted 
numerically, as whole values. For example, the color Gray 8 would appear before the 
color Gray 10. 

Scrolling To expedite the task of finding colors in a long list, the Color Namer supports 
all of the standard Macintosh scrolling methods. Besides responding to the scroll bar and 
the arrows, the Color Namer scrolls to names in the list that match a letter, word, or 
number typed at the keyboard. 

For example, to scroll to colors beginning with s, type s when the Color Namer 
dialog box is visible. Type gray and the Color Namer scrolls to the first color named 
gray in the list. Similarly, typing 5 produces the first color name starting with that 
number. When it searches, the Color Namer ignores case and blank spaces but not 
diacritical marks. 

Saving or canceling changes When you finish using the Color Namer, click OK to 
save your changes and close the Color Namer dialog box. Click Cancel to close the dialog 
box without saving your changes. For example, if you've made a color change that you 
don't like, you can click Cancel to prevent it from taking effect (thus discarding any other 
changes that you made as well). Before closing the Color Namer, MacX displays an alert 
box that asks whether you really want to discard your changes. 
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Adding new colors 

MacX allows you to specify new colors by using the Color Namer dialog box. 
To add a new color: 

Click New in the Color Namer dialog box. 

A dialog box appears, requesting that you enter a name for the new color. 

Please enter a name for that color 



[[ OK J ( Cancel ) 



Type a name for the color and click the OK button. 

The Color Wheel dialog box appears. 

Click in the color wheel to select the color you want, then click OK. 

When you click in the color wheel, the selected color appears in the top half of the 
display box, below the legend Change color. If the color that you want does not appear, 
keep clicking in the color wheel until it does. The color name will appear in alphabetical 
order in the Color Namer dialog box. 
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If you have RGB values for a particular color, you can enter them in the numerical fields 
shown in the following figure. Click OK, and your color will appear in the Color Namer 
dialog box. 




The scroll bar to the right of the color wheel controls color brightness. Dragging the 
scroll box down makes colors darker; dragging the scroll box up makes them brighter. 
For more information on the color wheel, see the Macintosh System Software User's 
Guide, Version 6.0 or the Macintosh Reference. 



Removing colors 

To remove a color, click its name and then click the Remove button in the Color Namer 
dialog box. (See Figure 5-5.) A warning box appears, asking if you are sure that you want 
to remove the color. Click OK to remove the color, or click Cancel to retain it. 
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Changing colors and color names 

MacX allows you to change colors by using the Color Wheel dialog box. This procedure 
is similar to adding a new color. 

To change a color: 

Double-click the color sample that you want to change, or click the color 
sample and then click the Set Color button. 

The Color Wheel dialog box appears. At the upper left, the sample color box displays the 
existing color. 

Click in the color wheel to find the color that you want. 

As you click the color wheel, the top half of the box reflects the color choices you have 
made, while the bottom half retains the original color so that you can compare them. 

When you find the color that you want, click OK. 

The Color Namer dialog box reappears, showing the changed color. 

If, for some reason, you want the original color back, click Cancel to close the Color 
Namer dialog box and discard the changes you have made. Alternatively, if you 
remember the original color's numerical values for red, green, and blue — or for hue, 
saturation, and brightness — you can type these numbers in the appropriate fields in the 
Color Wheel dialog box to restore the color. 

To change a color name, select the name by double-clicking or using the Set Name 
button. The Color Namer then displays a dialog box that lets you enter another name. 

Copying and pasting color names 

You can use the Copy command in the Edit menu, just as you would in any standard 
Macintosh application, to copy a color name to the Clipboard and paste it into a remote 
command or a client window. 

Once a color name is on the Clipboard, you can also paste it into a client command or 
file by using that client's paste or insert command. 
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6 Troubleshooting 



Consult this chapter when MacX displays an error message and you aren't sure what to 
do. Often the problem is easy to fix. In some cases, the problem may involve your 
network or the host that you are trying to reach, rather than MacX itself. If the problem 
does involve MacX and you aren't able to find a solution in this chapter, consult your 
system administrator. 



This chapter describes the following types of problems: 

■ problems that may occur when you first start MacX 

■ problems that may occur when you are trying to connect to an X client by executing a 
remote command 

■ problems related to the connection tools that you use with MacX 

■ problems that may be caused by the clients to which you're trying to connect 

■ problems related to the Font Directory file or to using X fonts 

■ problems related to using the keyboard with MacX 

■ problems that may occur when trying to print while using MacX 

■ problems that may occur when you try to save a MacX settings document 

■ problems that arise if you do not have enough memory in your computer available 
for use by MacX 

■ problems that may be caused by the connection between your Macintosh and the 
network or by the network itself 
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About alert messages 



MacX displays different types of alert messages, depending on the type and severity of 
the problem. If the problem involves a malfunction of MacX, the Macintosh hardware, or 
the operating system, MacX displays an alert box containing the phrase "Sorry — an 
internal error has occurred." Figure 6-1 illustrates this type of alert box. 




Sorry - an internal error has occurred: 



I °«_J 

Figure 6-1 An alert box for an internal error 

Usually, you can do nothing to fix this kind of problem yourself. Any time MacX 
displays an internal error message, call your system administrator. 

Another kind of error causes MacX to quit or prevents MacX from starting up. The 
phrase identifying this type of error is "An unexpected error has occurred." Figure 6-2 
illustrates the alert box displayed in this case. 




fln uneKpected error has occurred: 



| no 

Figure 6-2 An alert box for an unexpected error 
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Frequently, you can recover from an error of this type. If you get this type of error, 
refer to the section in this chapter that covers the problem that you have encountered. 

The third type of error message that MacX might display is a warning, such as the 
one shown in Figure 6-3. Warnings normally advise you of minor problems, such as a 
field you forgot to fill in, but do not cause MacX to quit. 



A The remote command "color Htlock" 
/ !\ attempted to use connection tool 

"MacTCPTool", which does not ewist. 



|om | 

Figure 6-3 A warning box 

For assistance with warnings, refer to the section in this chapter that covers the type of 
warning you encounter. 



Under certain circumstances an error can occur without your being notified by MacX. 
This type of error can happen if you make a mistake typing a remote command, your 
user name, or your password and you have selected the Save or Notify command output 
option in the Remote Command dialog box. 

If you selected the Save option, MacX saves any information from the host about your 
command that appears in the command's Output window, but you are not otherwise 
notified that a problem has occurred. 

If you selected the Notify option, your Macintosh beeps and displays a small, blinking 
MacX icon in the menu bar when MacX receives command output. 

In both cases, the intent is to spare you from having to deal immediately with every 
bit of information generated by the host. When something goes wrong, however, you 
have to display the Output window yourself to discover what system or error messages 
the host transmitted. If, instead, you prefer immediate notification, choose the Pop Up 
option from the Output menu. See "Creating New Commands" in Chapter 3 for 
information about this option. 
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Problems starting MacX 



The following messages describe errors that prevent the MacX application from starting 
or a MacX settings document from opening. Except where indicated, these errors appear 
in the unexpected-error alert box shown in Figure 6-2. 

Communications Toolbox not initialized because no connection tools installed 

The message "An unexpected error has occurred: the Communications Toolbox could 
not be initialized because there are no connection tools installed" indicates that the 
Communications Folder in your System Folder has no connection tools in it. 

If you forgot to install any connection tools, see the Installation part of the Network 
Services User's Guide. 

If you inadvertantly dragged your connection tool (or tools) out of the 
Communications Folder, drag it (or them) back in. 

Could not open the default cursor font 

A special font, called cursor, comprises all of the cursors used in X. MacX will not start up 
if it cannot open the cursor font. This message appears in this situation: "An unexpected 
error has occurred: could not open the default cursor font 'cursor.' Did you install the 
MacX Fonts?" Follow these steps: 

1. Verify that the cursor font file is in the MacX Fonts folder or one of its subfolders. 

Reinstall the font file by dragging a copy from the Misc folder in the MacX Fonts 
folder in the MacX application folder from the PATHWORKS VI. volume on your 
VAXshare file server. 

2. Verify that you have only one MacX Fonts folder, either in the System Folder or in the 
same folder as your MacX application. 

3. Restart your computer and try opening your MacX application or settings document 
again. 
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Could not open the default font "fixed" 

MacX uses a special font, called fixed, when writing text in a client window if the client 
has not specified a font for this purpose. MacX will not start up if it cannot open this font. 
This message appears in this situation: "An unexpected error has occurred: could not 
open the default font 'fixed.' Did you install the MacX Fonts?" Follow these steps: 

1. Verify that the fixed font file is in the MacX Fonts folder or one of its subfolders. 

Reinstall the font file by dragging a copy from the Misc folder in the MacX Fonts 
folder in the MacX application folder from the PATHWORKS VI. volume on your 
VAXshare file server. 

2. Verify that you have only one MacX Fonts folder, either in the System Folder or in the 
same folder as your MacX application. 

3. Restart your computer and try opening your MacX application or settings document 
again. 

Error opening or reading a settings document 

If your settings document is damaged, MacX displays this warning: "An error occurred 
when opening or reading your settings document— a new (Untitled) one will be used 
instead." The document is probably unusable. The message advises you that MacX has 
opened a new settings document since it could not open the one you specified. Be sure 
to throw the damaged document away. 

Initialization of the Communications Toolbox failed 

An error may occur when MacX tries to open the Macintosh Communications Toolbox. 
This message appears: "An unexpected error has occurred: Initialization of the 
Macintosh Communications Toolbox failed (error code «)." If this error message 
appears when you start up MacX, verify that the Communications Folder is in your 
System Folder. If no Communications Folder exists, see the Installation part of the 
Network Services User's Guide. 
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MacX requires that the Communications Toolbox be installed 

Before MacX can start, the Communications Toolbox must be installed in your System 
Folder. If it is not installed, the following message appears when you start MacX: "An 
unexpected error has occurred: MacX requires that the Macintosh Communications 
Toolbox be installed." See if there is a Communications Folder in your System Folder. 
If no Communications Folder exists, see the Installation part of the Network Services 
User's Guide. 



No connection tools are working at the moment 

The full text of this warning is as follows: "None of the connection tools are working at 
the moment — check that they are properly installed and restart MacX. Until this is done, 
no incoming X client connections can be accepted." If you see this warning when starting 
up MacX, check for these conditions: 

1. Is the network working? 

Check with your network administrator to verify that the network is working. If it is, 
go to step 2. 

2. Does your Communications Toolbox contain connection tools capable of supporting 
the X protocol (such as the AppleTalk-DECnet Connection Tool)? 

Some connection tools, such as the Serial Connection Tool and the Apple Modem 
Connection Tool, cannot supply the duplex, reliable byte-stream communications 
service that MacX needs to set up host connections. If you're not sure which tool(s) to 
use, check with your system administrator. However, if you already have the right 
connection tools, go to step 3. 

3. Are these connections tools installed correctly? 

Consult the installation procedures for your duplex, reliable byte-stream tool(s) to 
verify that they are installed correctly. (Your system administrator can help.) If 
everything is in order, restart your Macintosh and try starting MacX again. If the same 
message appears, call your system administrator or authorized Apple dealer for 
further assistance. 
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Not enough memory for MacX to run 

If the memory allocated to MacX is less than the suggested memory size in the Get Info 
dialog box, this error message appears: "There is not enough memory for MacX to run. At 
LEAST nnK more is required." (The nn in the message equals the number of kilobytes of 
memory required.) See "Memory-Related Problems," later in this chapter, for instructions 
on increasing the memory allocation for MacX. 

Not enough memory to start MacX 

If you are running under MultiFinder and the amount of random-access memory (RAM) 
available to run MacX is less than the MacX application memory size, this warning 
appears: "There is not enough memory to open 'MacX'... Do you want to open it using 
the available memory?" Usually, you can free more RAM by quitting from another 
application. 

MacX can run in less than its assigned application memory size if this amount is 
adequate to handle the types of activities that you perform. If not, MacX may run out of 
memory while you are performing an operation and display an error message to that 
effect. For more information, see "Memory-Related Problems," later in this chapter. 



Problems with remote commands 

This section describes errors that prevent remote commands from executing. Some of 
these errors involve problems with the host or network specified in the command. Others 
result from lack of sufficient memory. Unless identified as errors, these messages are 
warnings that appear in the alert box illustrated in Figure 6-3. 

The word cmdname appearing in any of the following error messages represents the 
name of the remote command in question. The word toolname represents the name of 
the connection tool in question. 
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Auto Execute commands could not be started 

The full text of this warning is as follows: "One or more 'Auto Execute' commands could 
not be started." This warning usually appears after other warnings that better identify the 
source of the problem. Normally, this error occurs when the host that you are trying to 
reach is not available or the connection tool that you are using is improperly installed. If 
you're not sure what the problem is, call your system administrator first to verify the 
status of the host. If the host is available, consult the documentation for the connection 
tool to verify that it is properly installed, or ask your system administrator for assistance. 

Creation of remote command stream failed 

When MacX doesn't have enough memory to build a connection to the host, it displays 
this warning: "The remote command 'cmdname' could not be executed via the tool 
'toolname. 'Creation of the remote command stream failed." 

<Connection tool error string appears here> 

As indicated, MacX also displays an error message or warning from the connection 
tool that should provide more information about the specific problem. For suggested 
ways to free memory, see "Memory-Related Problems," later in this chapter. Also see the 
troubleshooting section of your connection tool documentation for more information 
about the error or warning that the tool generated. 

Not enough memory 

MacX displays one of three warnings when it runs out of memory while processing a 
command: 

■ "Remote command did not succeed: there was not enough memory to perform the 
operation." 

■ "There is not enough memory to store the remote command in the MacX document." 

This warning appears when you attempt to save or execute a remote command that 
you have just edited or created and MacX does not have enough memory to store it. 

■ "There was not enough free memory to create a new remote connection." 

This warning appears when you execute a remote command and MacX does not have 
enough memory to set up a connection with the host. 
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To make more memory available, follow the suggestions in "Can't Use a MacX Feature," 
later in this chapter. 

Remote command tried to use connection tool that does not exist 

If you see the warning "The remote command 'cmdname' attempted to use connection 
tool 'toolname, 'which does not exist," the remote command named in the error message 
specifies a connection tool that you discarded or renamed sometime after you created the 
remote command. To correct the problem, edit your remote command and select a 
different connection tool from the Connection Settings dialog box. 



Problems with connection tools 

This section describes problems with connection tools. These problems prevent remote 
commands from executing. 

Setup options rejected by the connection tool 

This error message appears if you haven't configured the setup options correctly or if 
you've placed a different version of the connection tool used to set up the current options 
in the remote command that you tried to execute: "The setup options you specified in the 
Connection Setup dialog were rejected by the connection tool. The default setup for the 
tool has been substituted." Consult your connection tool documentation to find out 
which setup options are appropriate, and re-create the remote command with the current 
version of the connection tool. 

The X client cannot connect to MacX 

A frequent cause of this problem is the presence in your Connection Folder of more than 
one connection tool that supports the same network protocol (connection method). For 
example, if you have two copies of the AppleTalk-DECnet Connection Tool (saved with 
different names) in your Connection Folder, neither tool may work properly. 
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Problems with clients 



This section describes problems that might occur while you are running X clients. 
The X client cannot connect to MacX 

A frequent cause of this problem is the presence- in your Connection Folder of more than 
one connection tool that supports the same network protocol (connection method). For 
example, if you have two copies of the AppleTalk-DECnet Connection Tool (saved with 
different names) in your Connection Folder, neither tool may work properly. 

Client windows suddenly disappear 

When dialog or alert boxes appear on your screen, MacX stops responding to requests 
from active clients and waits for your reply. MacX also waits in this manner while you are 
working in a large Macintosh application, such as MacDraw®, that requires all the system 
resources to perform tasks such as updating the screen. 

After about ten minutes, clients that haven't received any responses to their requests 
will quit running, a condition called timing out. However, the client windows will remain 
on the screen until you release MacX by closing the dialog or alert box, or until the 
operating system finishes updating your other application. MacX will then detect which 
clients have timed out and close their windows without explanation. 

To prevent this sudden disappearance of clients from your screen, respond to dialog 
and alert boxes as soon as possible and try not to monopolize system resources on a 
single task for more than a few minutes. 

All client windows appear in black and white on a Macintosh that 
supports color 

For clients that you want to appear in color, make sure that you've specified that the 
client is displayed on one of the color screens (either 2 or 3). Table 6-1 lists the screen 
numbers along with their descriptions. 
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Table 6-1 Screen numbers 



Screen number 



Description 



3 







2 



Monochrome screen, rootless style 
Monochrome screen, rooted style 
Color screen, rootless style 
Color screen, rooted style 



Note: Machines that don't support Color QuickDraw, namely the Macintosh Plus and Macintosh SE, 
do not support screen numbers 2 and 3. 

For more information, see "What You See on the Screen" in Chapter 1 and "Specifying 
Screen Numbers" in Chapter 3. 

The alert "Are you running another window manager?" appears 

MacX comes with a built-in window manager for its rootless screens (0 and 2). If you run 
a remote window manager and specify that it should manage either of these screens, or if 
the remote window manager manages all screens by default, this message may appear. It 
is not possible to override the MacX Window Manager on rootless screens. Use rooted 
screens if you need a separate window manager. 

Using the Pause feature of the DECwindows Session Manager causes MacX to 
run out of memory 

The Pause feature of the DECwindows Session Manager should not be used with MacX. 
The Pause feature creates a single window large enough to completely cover all of the 
screens attached to your X server. Because MacX actually simulates four screens (on 
Macintosh computers that support color), the Session Manager must allocate a large 
amount of memory to windows large enough to cover the entire Macintosh desktop. A 
low-memory condition may result. 
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Problems with fonts 



This section describes errors that prevent MacX from updating the Font Directory file or 
that prevent you from using a font. Figure 6-3 depicts the type of alert box in which these 
warnings appear. The word fontname in any of the following commands represents the 
name of the font in question. The expression "(«)" represents an error code. 

Could not open the default cursor font 

A special font, called cursor, comprises all of the cursors used in X. MacX will not start up 
if it cannot open the cursor font. This message appears in this situation: "An unexpected 
error has occurred: could not open the default cursor font 'cursor.' Did you install the 
MacX Fonts?" Follow these steps: 

1. Verify that the cursor font file is in the MacX Fonts folder or one of its subfolders. 

Reinstall the font file by dragging a copy from the Misc folder in the MacX Fonts 
folder in the MacX application folder from the PATHWORKS VI. volume on your 
VAXshare file server. 

2. Verify that you have only one MacX Fonts folder, either in the System Folder or in the 
same folder as your MacX application. 

3. Restart your computer and try opening your MacX application or settings document 
again. 

Could not open the default font "fixed" 

MacX uses a special font, called fixed, when writing text in a client window if the client 
has not specified a font for this purpose. MacX will not start up if it cannot open this font. 
The following message appears in this situation: "An unexpected error has occurred: 
could not open the default font 'fixed.' Did you install the MacX Fonts?" Follow these 
steps: 
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1. Verify that the fixed font file is in the MacX Fonts folder or one of its subfolders. 

Reinstall the font file by dragging a copy from the Misc folder in the MacX Fonts 
folder in the MacX application folder from the PATHWORKS VI. volume on your 
VAXshare file server. 

2. Verify that you have only one MacX Fonts folder, either in the System Folder or in the 
same folder as your MacX application. 

3. Restart your computer and try opening your MacX application or settings document 
again. 

Error getting information about MacX Fonts folder 

The full text of this error message is as follows: "An unexpected error has occurred: Error 
(ri) getting information about the 'MacX Fonts' folder. Did you forget to install the MacX 
Fonts?" If the message does not occur for the reason stated, it means that your fonts folder 
has been damaged by a disk error, power surge, or some other rare mishap. To solve the 
problem, throw away the existing MacX Fonts folder and reinstall the font file by 
dragging a copy from the MacX Fonts folder in the MacX application folder from the 
PATHWORKS VI. volume on your VAXshare file server. 

Error updating Font Directory file 

The full text of this warning is as follows: "The 'Font Directory' file (in your 'MacX Fonts' 
folder) needs to be updated, but an error (ri) occurred when it was being written. MacX 
can continue, but problems may be encountered when opening new fonts." You will 
probably not be able to open new fonts until the Font Directory file can be updated. After 
following these steps to discover and correct the problem or problems, start MacX or 
open a settings document to automatically update the Font Directory file. 

1. Is the Font Directory file locked? 

Find the Font Directory file in the MacX Fonts folder. Click the file icon, choose Get 
Info from the File menu, and make sure that the box labeled Locked in the upper-right 
corner of the Get Info box is not checked. 
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2. Does MacX have sufficient RAM? 

Some operations in MacX, such as displaying color windows, use a lot of memory. 
Running several X clients simultaneously also takes a lot of memory. To ensure that 
MacX has enough memory to update the Font Directory file, try the suggestions in 
"Can't Use a MacX Feature," later in this chapter. Then try updating the Font Directory 
file again by starting MacX or opening a settings document. If you get the same error 
message, go to step 3. 

3. Is the MacX Fonts folder on a disk to which you can't write? 

Make sure the disk isn't write-protected. If it is a floppy disk, verify that you cannot 
see through the square hole on the upper-left side of the disk. Otherwise, slide the 
black locking tab down so that the hole is blocked. If the MacX Fonts folder is on a 
file server, click the file-server icon, choose Get Privileges from the File menu, and 
verify that you have the privilege to make changes. Repeat this procedure to check 
the MacX Fonts folder itself and any folder in which it is stored. 

4. Is your disk full? 

Check the upper-right corner of your disk directory folder for the amount of available 
free disk space. 

5. Is the disk you are using defective? 

Run the Macintosh utility called Disk First Aid™ or an equivalent to ensure that your 
disk is not damaged. The Macintosh Utilities User's Guide and the Macintosh 
Reference contain instructions for using Disk First Aid. 

Font Directory file has been damaged. 

The text of this warning is as follows: "The 'Font Directory' file has been somehow 
damaged. A new 'Font Directory' file will be created from scratch to be used instead." 
Probably a disk error, power surge, or similar accident has corrupted the file. Since the 
new file will not have the aliases or Macintosh fonts that you added, consider restoring an 
old version of the Font Directory file if you have one. 
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Font property could not be loaded 

If a font file is corrupted, MacX displays this warning: "For some reason, the FONT 
property of the font file 'fontname' couldn't be loaded. This font will be left out of the 
Font Directory list and thus will be unavailable for use." When this error occurs, drag the 
corrupted font file to the trash and get a new copy of the file from your MacX 
distribution disk or compile a new font file. After dragging the file into the appropriate 
folder in the MacX Fonts folder, click the Update Font Directory button in the Font 
Director dialog box to insert the font in the Font Directory list. See Chapter 5 for 
instructions for compiling fonts. 

Font file is malformed 

The warning "The font file fontname' is malformed and could not be opened" means 
that the file for the font that you selected is missing or damaged. Reinstall the font file by 
dragging a copy from the MacX Fonts folder in the MacX application folder from the 
PATHWORKS VI. volume on your VAXshare file server. 

Not enough memory to add font name to the list of known fonts 

Receiving the warning "Unable to allocate enough memory to add the font name 
'fontname 'to the list of known fonts" means that MacX has run out of memory to 
perform this operation. Close any unnecessary windows, clients, or applications to 
release the memory dedicated to them and try your command again. Also, see "Can't Use 
a MacX Feature," later in this chapter, for more suggestions on how to increase the 
amount of available memory. 

One or more fonts could not be matched against the pattern fontname 

If you receive the warning "Due to a memory allocation failure, one or more font names 
could not be matched against the pattern fontname' during the servicing of a client 
request," MacX does not have enough memory available to display the font that you 
requested. Close any unnecessary windows, clients, or applications to release the 
memory dedicated to them and try your command again. Also, see "Can't Use a MacX 
Feature," later in this chapter, for more suggestions on how to increase the amount of 
available memory. 
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Unable to delete the selected font 

MacX displays one of two warnings when it cannot delete a font: 

■ "Unable to delete the selected font because you do not have sufficient access 
privileges to delete the font file." 

This warning occurs when the font file(s) in question are locked, the MacX Fonts 
folder is on a disk or in a folder to which you don't have write-access, or the Font 
Directory file is locked. Perform these steps, in the order given, until you discover the 
source of your problem. Then try removing the fonts again. 

1 . Is the font file or the Font Directory file locked? 

Find the font file in the MacX Fonts folder. Click the file icon, choose Get Info 
from the File menu, and make sure that the box labeled Locked in the upper-right 
corner of the Get Info box is not checked. If the font file is not locked, use the 
same procedure to see if the Font Directory file is locked. 

2. Is the MacX Fonts folder on a disk or in a folder to which you cannot write? 
Make sure the disk or folder isn't write-protected. If it is a floppy disk, verify that 
you cannot see through the square hole on the upper-left side of the disk. 
Otherwise, slide the black locking tab down so that the hole is blocked. If the 
MacX Fonts folder is on a file server, click the file-server icon, choose Get 
Privileges from the File menu, and verify that you have the privilege to make 
changes. Repeat this procedure to check the MacX Fonts folder itself, and any 
folder in which it is stored. 

■ "Unable to delete the selected font, error code w." 

The n represents an error code number. This warning occurs very rarely. If it appears, 
record the error code number and call Technical Support at Apple Computer. Ask one 
of the technicians to interpret the error code for you and explain how to solve the 
problem. 
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Problems 



with the keyboard 



This section describes problems related to using the keyboard. 

You have problems inserting text with a MacroMaker script 

You cannot use MacroMaker to insert text keystroke by keystroke into X client windows. 
MacroMaker never issues key-release events to MacX, so MacX acts as if the keys are being 
held down continuously. This problem may also occur with other keyboard macro utilities. 

MacX beeps when you enter some international and special-symbol characters 

To conform to the X protocol, MacX must translate your typing into a predefined set of 
X key symbols. This predefined set contains the ISO Latin-1 character set plus a 
number of special-purpose keys, such as the Return key. If you enter a character that 
cannot be translated from its Macintosh representation into one of the X symbols, MacX 
beeps to inform you that the character is unavailable. 



If you get a warning stating that an error occurred when attempting to print, you most 
likely forgot to select a printer name. Instructions in the following section explain how to 
identify and correct such problems. If the error concerns opening the printer driver, read 
the subsequent printer driver section for troubleshooting instructions. 

Error occurred when attempting to begin printing or to print a page 

The two warnings "An error occurred when attempting to begin printing" and "An error 
occurred when attempting to print a page" are triggered by the same events. Perform 
these steps to discover the source of the problem. Then try printing again. 



Problems 



with printing 
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Is the printer driver installed correctly? 

Verify that an icon for a printer, such as a LaserWriter® or ImageWriter®, appears in 
the upper-left list in the Chooser window. If no printer icon appears, you must 
install one. For instructions, see "Using the Chooser With Devices on AppleTalk" in 
the chapter on desk accessories in the Macintosh System Software User's Guide, 
Version 6.0. 

Did you select a printer? 

To check, open the Chooser, click a printer icon, and verify that a printer name is 
highlighted. (See Figure 6-4.) 



Error occurred when attempting to open your printer driver 

The warning "An error occurred when attempting to open your printer driver" means that 
the driver software for your printer is either malfunctioning or not installed. To fix this 
problem, open the Chooser from the Apple menu. 

When the Chooser window appears, verify that an icon for a LaserWriter, 
ImageWriter, or other printer appears in the upper-left list, as shown in the Figure 6-4. 
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Figure 6-4 The Chooser window 



If no printer icon appears, you must install one. For instructions, see "Using the Chooser 
With Devices on AppleTalk" in the chapter on desk accessories in the Macintosh System 
Software User's Guide, Version 6.0, or see Chapter 8 in the Macintosh Reference. If you 
do see a printer icon, click it and select a printer name from the list that appears on the 
right. Now close the Chooser and try choosing Print Clipboard again. 
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Problems saving a settings document 



This section describes problems that may occur while saving a settings document. 
Error occurred while saving document 

Several types of errors can prevent MacX from saving a settings document. Each of these 
errors generates the warning "An error occurred while saving your settings document; the 
document could not be saved." Perform these steps until you solve the problem: 

■ Does MacX have sufficient memory? 

Some operations in MacX, such as displaying color windows, use a lot of memory. 
Running several X clients simultaneously also takes a lot of memory. Follow the 
suggestions in "Can't Use a MacX Feature," later in this chapter, to make memory 
available, and then try to save your settings file again. 

■ Is the disk that you are using defective? 

Use the Save As command to save your document to a floppy disk (or another hard 
disk if you have one). Then, run the Macintosh utility called Disk First Aid or an 
equivalent to ensure that your disk is OK. The Macintosh Utilities User's Guide 
contains instructions for using Disk First Aid. 

■ Is your settings document on a disk to which you don't have write-access? 

Make sure you have write-access to the disk. If it is a floppy disk, verify that you 
cannot see through the square hole on the upper-left side of the disk. Otherwise, 
slide the black locking tab down so that the hole is blocked. If the settings document 
is on a file server, click the file-server icon, choose Get Privileges from the File menu, 
and verify that you have the privilege to make changes. Repeat this procedure to 
check any folder in which the settings document is stored. 

■ Is your disk full? 

Check the upper-right corner of your disk directory folder for the amount of available 
disk space. For example, the following figure shows 6,781 K available. 
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Settings document is corrupted or created by very old version of MacX 

The full text of this warning is as follows: "The settings document is corrupt or was 
created by a very old version of MacX. A new (Untitled) one will be used instead." This 
warning means that your document is corrupted (damaged) or is incompatible with the 
version of MacX that you are using. 



Memory-related problems 

Not having enough memory can prevent you from either (1) starting MacX or opening a 
MacX settings document or (2) using a feature in MacX after the application is open. 
Because it's sometimes difficult to know how much memory certain X clients and 
operations require, MacX alerts you when memory is low so that you can avoid major 
disruptions to your work. This section explains the low-memory warning system and 
suggests several ways to free memory so that you can avoid memory-related problems in 
the future. 

Low-memory warning system 

MacX attempts to keep 128K of memory in reserve at all times. When it must dip into this 
memory reserve, MacX notifies you that its memory supply is low by beeping once and 
alternating a caution symbol (A) with the apple icon (ft) at the top of the Apple menu. 
If you are running under MultiFinder and MacX is not in the foreground, a diamond 
appears next to the entry for MacX in the list of open applications at the bottom of the 
Apple menu. 

Choosing About MacX from the menu displays the About MacX window shown in 
Figure 6-5. On the lower right side of the window, a bar graph displays how much 
memory MacX has left. At minimum, MacX should have 128K of memory free. However, 
if you plan to run a lot of clients, especially color clients, allowing MacX a few hundred 
kilobytes of free memory is more realistic. 
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Figure 6-5 The About MacX window 

When MacX displays the caution symbol, you can quickly free more memory by closing 
any MacX windows or clients that you don't currently need. If you release enough 
memory to replenish the memory reserve, MacX cancels the memory alert and the 
caution symbol disappears. However, if MacX is constantly notifying you of memory 
shortages, closing windows is not a good, long-term solution for your memory problems. 
You should probably increase MacX's application memory size, add more memory (RAM) 
to your machine, or both. If the caution symbol appears as soon as MacX begins running, 
you should definitely quit and increase MacX's application memory size. Read the next 
two sections, "Can't Start MacX" and "Can't Use a MacX Feature," for further instructions. 

Can't start MacX 

If you get an alert stating that there is not enough memory to start MacX, the problem 
may be that there isn't a large enough block of contiguous memory available. This 
situation can arise when you are running under MultiFinder and you open, close, and 
reopen a number of applications. The unused memory in your Macintosh may be divided 
into blocks too small to run MacX or other applications. Follow these steps to solve the 
problem. 

1. Check your system's total memory to see if it has sufficient RAM. 

Choose About the Finder from the Apple menu and check the Total Memory field to 
see how much RAM your Macintosh has. (In the following figure, the total memory 
available is 4 megabytes.) If your system is running MultiFinder, it should have at least 
2 megabytes to operate smoothly; otherwise, restart your Macintosh under the 
Finder™ and try running MacX again. 
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2. Check MacX's application memory size. 

If your system has plenty of memory available to support MultiFinder, you still may 
not have enough memory left over to run MacX. You'll know that this is the case if 
MacX displays a blinking caution symbol in the menu bar. To find out, choose About 
MacX from the Apple menu and see how much free memory remains. If the memory 
available is less than 128K, quit MacX if it's running, click the MacX icon, choose Get 
Info from the File menu, and check the field labeled Application Memory Size (K). 




Kind : application 

Size: 698,286 bytes used, 682K on disk 
Vhere: Chez Metz, SCSI 

Created : Wed, Jan 1 0, 1 990, 7 :09 PM 
Modified : Thu, Jan 1 8, 1 990, 2 :50 PM 
Version : 1 .0, © 1 988, 1 989, 1 990 Apple 
Computer, Inc. 



Suggested Memory Size 00 : 1 500 
Application Memory Size (K): 1500 



If the amount shown is larger than the amount shown in the Largest Unused Block 
field in the About the Finder window, free some memory as described in step 3. 
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If the application memory size is smaller 'than the suggested memory size, MacX is 
probably being assigned less memory than the minimum required for it to operate. To 
increase the allocation, enter a larger number in the Application Memory Size field of 
the Get Info window. 

3. Increase the size of the largest unused block. 

If the amount in the Largest Unused Block field in the About the Finder window is too 
small, save, quit, and reopen all the applications currently running. This exercise 
causes the system to restart the applications in contiguous blocks of memory so that 
any unused memory occupies one contiguous block rather than being broken into 
unusable fragments. 

However, if the largest unused block is still too small to run MacX, you have a 
number of alternatives: 

□ Close other applications running under MultiFinder. In the figure shown in Step 1, 
AppleLink® and Microsoft Word could be closed to free more memory. 

□ Remove unnecessary initialization resources (INITs), Control Panel devices, fonts, 
and desk accessories from your System Folder. Simply drag the INITs and Control 
Panel devices that you don't need out of your System Folder. To remove fonts and 
desk accessories, use the Font/DA Mover. In both cases, restart your Macintosh to 
make these changes take effect. 

□ Choose the Control Panel from the Apple menu and turn the RAM cache off or 
reduce the amount of RAM set aside for it. 

□ Decrease the application memory size for MacX below the size of the largest 
unused block. MacX requires a minimum of 1024K to operate. MacX should not 
be locked— that is, the box labeled Locked in the upper-right corner of the Get 
Info window should not be checked. If it is, you won't be able to make this 
change. 

As a last resort, if none of these alternatives is a good solution in your case, consider 
buying more RAM for your computer. 
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Can't use a MacX feature 

Some operations in MacX, such as displaying color windows, use a lot of memory. 
Running several X clients simultaneously also takes a lot of memory. When you see an 
error message stating that there isn't enough memory to perform an operation, try the 
following suggestions to free memory: 

■ Close any color, rooted, or large windows that you don't need to use presently. 

■ If you are using numerous connection tools to run several sessions, close some of 
these connections. 

■ Close clients that are using large pixmaps. Some color clients require these. 

■ Reduce the number of different fonts being used at the same time. 

■ Delete the remote command output for commands that have finished executing. To 
delete this output, select the Command Output submenu from the Remote menu. 

■ Close the Remote Command dialog box, Font Director dialog box, and other MacX 
dialog boxes and windows if they are open. 

■ Increase the application memory size of MacX as described in step 2 in "Can't Start 
MacX," earlier in this chapter. 

Critical requirement for memory could not be satisfied 

When a memory shortage is particularly grave, MacX has just enough memory to display 
the message "An unexpected error has occurred: A critical requirement for memory could 
not be satisfied" and quit. If this message appears when MacX is starting up, increase the 
application memory size for MacX, as described in step 2 of "Can't Start MacX," earlier in 
this chapter. In most cases, increasing the application memory size is the best solution, 
especially if you are going to frequently perform the operation that generated this error. 

Not enough memory to resize window or show root window 

These warnings indicate that MacX has run out of enough memory to perform the stated 
operation: "There is not enough memory to resize the window 'title' right now" and 
"There is not enough memory to show the 'title' root window right now." See the 
suggestions in "Can't Use a MacX Feature," earlier in this chapter, to make more memory 
available. (The word title stands for the title of the window that generated the warning.) 
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Serious memory allocation failure killed XI 1 client 

MacX displays this warning when it does not have enough memory to execute a remote 
command and display a client: "A serious memory allocation failure has forced an XI 1 
client application to be killed." If you have other clients and windows open, you can close 
some of them and try your command again. However, if this command was the first that 
you tried to execute (and nothing else was running), quit MacX and increase its application 
memory size, as described in step 2 of "Can't Start MacX," earlier in this chapter. 



Network-related problems 

If one of the scenarios in the following list describes a problem that you're having, the 
problem could be related to the network hardware or software that you're using. 

The Control Panel is missing. 

The Control Panel is present on all startup disks unless you have removed it with the 
Font/DA Mover. If you're using more than one startup disk, your Macintosh may switch 
to a disk without the Control Panel installed. The icon of the current startup disk is in the 
upper-right corner of the desktop. 

Use the Installer application from the System Tools disk (version 6.0.4 or a later 
version) to update your System file. The Installer automatically reinstalls the Control 
Panel. 

The Network icon is missing from the Control Panel. 

In this case, one of the following problems exists: 

■ You don't have the EtherTalk 2.0 software installed correctly on your startup disk. 
See the documentation for the Ethernet card that you are using. 

■ The Network icon has been moved from your System Folder. You must reinstall 
the EtherTalk 2.0 software. See the documentation for the Ethernet card that you 
are using. 
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■ Your startup disk has the wrong version of the Control Panel. You must use version 
3.1 or a later version. (The version number appears in the lower-left corner of the 
Control Panel). Use the Installer application from the System Tools disk (version 6.0.4 
or a later version) to update your System file. The Installer automatically reinstalls the 
Control Panel. 

You can't select the Network icon in the Control Panel. You get a message 
advising you that the network package has not been installed correctly. 

The EtherTalk 2.0 software has not been installed properly on your startup disk. See the 
documentation for the Ethernet card that you are using. 

The EtherTalk icon doesn't appear in the Control Panel after you click the 
Network icon. 

One of the following problems exists: 

■ You don't have the EtherTalk 2.0 software installed correctly on your startup disk. See 
the documentation for the Ethernet card that you are using. 

■ The EtherTalk icon has been moved from your System Folder. You must reinstall the 
EtherTalk 2.0 software. See the documentation for the Ethernet card that you are 
using. 

■ There is no Ethernet card in your Macintosh, or the card is not working properly. If a 
card is installed, see its documentation. 
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Two or more EtherTalk icons appear in the Control Panel when you click the 
Network icon. 

One of the following conditions exists: 

■ You have multiple Ethernet cards installed. The number in parentheses next to each 
icon's name identifies the slot containing the card. 

■ Earlier versions of EtherTalk software exist on your startup disk. Earlier versions are 
identified by single-arrow icons; icons for version 2.0 (or later versions) are identified 
by double arrows. PATHWORKS for Macintosh requires that you use EtherTalk 
version 2.0. See the documentation for the Ethernet card that you are using. 

If you want to remove the previous version of EtherTalk, find its icon in the System 
Folder and drag it to the Trash. 

You can't select the EtherTalk icon in the Control Panel. You get a message 
advising you that an error occurred while trying to install EtherTalk. 

You did not start your Macintosh with an EtherTalk startup disk, or the disk that you used 
has become damaged. Try reinstalling the EtherTalk 2.0 software. See the documentation 
for the Ethernet card that you are using. 

You are unable to select an EtherTalk icon in the Control Panel to switch the 
network connection. You get a message that the connection cannot be changed 
now, or that doing so will disrupt a critical service that your computer provides 
(such as an Apple§hare® file server or a router). 

If you can't switch the network connection, quit all applications and try switching the 
network connection again. If you still can't switch network connections, and you don't 
mind disrupting services that your computer provides or is using, shut down your 
Macintosh. Then restart your computer, using a startup disk that permits network- 
connection changes. Finally, try switching the network connection again. 
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Your Macintosh computer hangs (does not respond to the mouse and keyboard 
actions). 

Your Macintosh may hang for a minute or so when you select an EtherTalk icon or when 
you start up your computer. The computer can hang if it is not correctly connected to the 
Ethernet cable or the Ethernet card is not configured correctly. See the documentation for 
the Ethernet card that you are using. 

The Connection Settings dialog box does not list any network services or does 
not list the service that you want. 

■ If no network services appear, check the physical connection between your 
Macintosh and the network. See the suggestions later in this section for checking your 
network. 

■ If you switched the network connection in the Control Panel (as described earlier in 
this chapter) while the Connection Settings dialog box was open, the services listed in 
the dialog box may not have been updated. Close the Connection Settings dialog box 
and reopen it to view the services on the newly selected network. 

You can't select devices connected to the printer port of your Macintosh. 

If the Chooser does not let you select an Image Writer printer or other device connected 
to the printer port while the EtherTalk network connection is selected, you probably have 
an old version of the Chooser on your Macintosh. You must have Chooser version 3.4 (or 
a later version) to select a device on the printer port. Use the Installer application from 
System Tools disk (version 6.0.4 or a later version) to update your System file. The 
Installer automatically updates the Chooser. 
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Here's a checklist to consult whenever you're having trouble with Ethernet: 

■ Are all cables secure? 

Make sure that the network cable to your Ethernet card is secure at all connections. 
Also check the network cable to the service that you're trying to use. Contact your 
system administrator if you are uncertain about cable configuration. 

■ Is the problem really related to the network? 

Sometimes a problem that seems to be related to the network is actually related to the 
device or application program that you're using. The manual for the device or 
application may be helpful. 

■ Is your Ethernet card installed and set correctly? 

Shut down your Macintosh and make sure that the Ethernet card is firmly seated in its 
slot. Also, make sure that any jumpers and switches are set properly. See the 
documentation for your Ethernet card. 

■ Is the application that you want to use available on your network? 

You may have more than one network to which you can connect. Use the Control 
Panel to select the proper network connection. See "Selecting a Network" in 
Chapter 2 for instructions. 
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Appendix A: MacX Versus 
Other X Servers 



This appendix explains the difference between MacX and conventional X servers. This 
appendix also describes the miscellaneous preference for slower but smoother 
animation. Programmers should find this information useful. 



Client incompatibilities 



MacX handles the requests and clients named in this section differently than conventional 
X servers. 



Backward compatibility 

MacX tolerates some types of erroneous GrabPointer and Change WindowAttributes 
protocol requests so that older clients that don't adhere to X11R4 specifications can 
operate without receiving error messages. Some X11R4 servers have an extension that 
allows people to turn this backward-compatibility concession on or off. However, MacX 
does not support this extension, so backward compatibility is always in effect. 

Cursor size and movement 

MacX supports cursors up to 16 by 16 pixels in size. It truncates larger cursors to the 
upper-left l6-by-l6 area and forces the cursor's hotspot into that area. 

Most X servers have the capability to constrain movement of the mouse pointer, but 
this feature is disabled in MacX. Essentially, MacX ignores the ConfineTo field of 
GrabPointer and GrabButton requests so that it never prevents the cursor from moving in 
any way. This minor deviation enables people to move their mouse cursors to the menu 
bar and to windows of other Macintosh applications. 



Printing images of rootless windows 

The Print Screen menu commands in the DECwindows Session Manager do not work 
with clients displayed in a rootless style. The Print Screen commands normally work by 
printing all or part of the root window. Because there is no root window for rootless 
clients, there is nothing to print. 
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Standard colormaps 



MacX contains the functionality of xstdcmap, the X11R4 client that creates standard 
colormaps that perform color translation. Accordingly, MacX creates all the standard 
colormaps for screens 2 (color, rootless) and 3 (color, rooted), so that you don't have to 
run this client. 



Other differences 

This section identifies various features and procedures that are unique to MacX or that 
MacX handles differently than conventional X servers. 



Animation and mouse-movement preferences 

MacX has a miscellaneous preference option, Smoother (but Slightly Slower) Animation, 
that improves animation on a Macintosh screen. This option directs MacX to refresh the 
screen image of the off-screen bitmap after every X request that causes graphics changes 
in any window. If the preference is off, MacX updates the screen either when it is waiting 
to service an XI 1 request or when a quarter of a second has elapsed since the last screen 
update. Checking this preference eliminates delays between screen image updates. 

Another miscellaneous preference, Enable Mouse Movement Under Client Control, 
implements mouse warping when checked. However, clients can warp the mouse only 
in the part of the window that appears on the screen, not in any areas that are scrolled-off 
the screen nor in areas that extend beyond the screen boundaries. To find these two 
preferences, choose Miscellaneous Preferences from the Edit menu. 



Color-related differences 

If the Macintosh Clipboard contains a PICT object, MacX converts that object to a 
standard X bitmap selection. However, MacX cannot convert color objects to pixmap 
selections, so these graphics are converted to monochrome bitmaps. 
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MacX supports six visuals on both color screens (2 and 3). These visuals are 8-bit 
PseudoColor, 8-bit DirectColor, Grayscale, StaticGray, StaticColor, and TrueColor. In 
addition, MacX tries to display clients that require more than 8-bit color as well as 
possible. A visual is a structure that defines a method of using color resources on a 
screen. 



Font-path searching 

In order to reduce the complexity of handling fonts and to maintain a Macintosh-like user 
interface, MacX does not support the X font-path search function. It ignores font-path 
search requests from clients. The only impact on the person using fonts in MacX is that all 
X Fonts must be kept in the MacX Fonts folder or one of its subfolders. 



Resetting the server 

MacX performs a complete server reset operation whenever the user opens a new 
settings document or resizes the root window. This operation frees all existing properties 
on windows, all existing atoms, and all existing storage owned by the server. It is 
analogous to quitting from MacX and restarting it. 



Screen definitions 

Normally, a video display device can display one X screen: either a monochrome root 
window or a color root window. On video display devices capable of displaying both 
types of screens, the screens are mutually exclusive. Moreover, each video display device 
is assigned a unique screen number. In contrast, a Macintosh running MacX supports four 
screens (0 through 3) on one or more display devices. These screen numbers represent 
different root and window styles (rooted, rootless, monochrome, color) rather than 
individual video display devices, because the Macintosh views all display devices 
attached to it as one large, continuous desktop. 
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Typing international characters 



MacX conforms to the standard Macintosh method for typing international characters, 
that is, holding down the Option key and pressing another character to obtain 
diacritical marks, such as grave accent C), circumflex (a), and tilde (~). For example, 
on the U.S. keyboard, pressing the Option key and the / key together and then typing 
another letter produces a circumflex over that character. Use the Key Caps desk 
accessory to see what keys to press on your keyboard to obtain these marks. For more 
information, consult your Macintosh System Software User's Guide or the Macintosh 
Reference. 

Appendix E contains a matrix indicating the hexadecimal equivalents for ISO 
Latin 1 and Macintosh extended ASCII characters. These characters do not always 
have the same character-code value when translated from one character set to the 
other. 



Other differences 129 



Appendix B: The MacX 
Window Manager 



The MacX Window Manager controls the appearance and manipulation of windows in 
rootless mode, extending the Macintosh look and feel to the conventional X 
environment. This appendix explains the more technical aspects of some of its features. 



Transferring text and graphics 
between clients 



In conformance with the ICCCM, the MacX Window Manager enables you to cut, copy, 
and paste text and graphic objects in PICT format from one client to another. To transfer 
text or graphics, use the client's method to perform the cut, copy, or paste operation. 
MacX is advised of a cut or copy event and places the selected item in the Clipboard. 
When you indicate where you want to paste the item, by issuing the appropriate 
command within the client you want to receive it, MacX transfers the contents of the 
clipboard to that client. For example, to paste your selection in a terminal emulator 
window, you would press the left arrow key, the equivalent in MacX to pressing the 
middle mouse button. 

As discussed in Chapter 1, the MacX Window Manager also enables you to cut, copy, 
and paste text and graphic objects in PICT format from Macintosh applications to XI 1 
clients. If the Macintosh Clipboard contains a PICT object, MacX converts that object to a 
standard XI 1 bitmap selection. Note that MacX does not support conversion of color 
PICTs to pixmap or colormap selections. Color Clipboard objects are converted to 
monochrome bitmap selections. 

MacX can also copy and paste text, such as font or color names, from MacX dialog 
windows (the Remote Command window, Font Director window, and Color Namer) to 
clients using substantially the same operation. See the section "Editing Commands" in 
Chapter 1 for a summary of these procedures. 
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Window positioning 



The MacX Window Manager automatically positions a window if its coordinates would 
otherwise position it completely off of any screen, if the command to create it specifies 
no geometry option, or if the x-y coordinates specified in the geometry option are 0,0. 
MacX positions such windows in a cascading sequence starting from the upper-left 
comer of the screen that is most appropriate to display the window. Color windows 
are automatically positioned in a sequence on color screens and monochrome 
windows are automatically positioned on monochrome screens. If no appropriate 
screen exists for a window, it is automatically positioned on the screen containing the 
MacX menu bar. 

The point of origin of rootless-style windows is the left corner on the inside edge 
of the border, so you should account for the height of title bars when specifying the y 
coordinate. 
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Appendix C: Bitmap Distribution 
Format 2.1 



This appendix contains a copy of the document, Bitmap Distribution Format 2.1, written 
by Adobe Systems, Inc. It is provided as a reference to programmers who want to 
compile fonts from BDF files. 



Bitmap Distribution Format 2.1 



Copyright © 1984, 1987, 1988 Adobe Systems, Inc. 

Permission to use, copy, modify, and distribute this 
software and its documentation for any purpose and without 
fee is hereby granted, provided that the above copyright 
notice appear in all copies and that both that copyright 
notice and this permission notice appear in supporting 
documentation. 
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Bitmap Distribution Format i 

Table of Contents 

1. Introduction 1 

2. File Format 1 

3. Metric Information 3 

4. An Example File 6 
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Bitmap Distribution Format 



List of Figures 

Figure 3-1: An example of a descender 4 
Figure 3-2: An example with the origin outside the bounding box 5 



Xll BDF Version 2.1 



138 Appendix C Bitmap Distribution Format 2.1 



Bitmap Distribution Format 



1. Introduction 

This document describes Bitmap Distribution Format (BDF), version 2.1. BDF is an X 
Consortium standard for font interchange, intended to be easily understood by both humans and 
computers. 



2. File Format 

Character bitmap information will be distributed in an USASCII encoded, human readable form. 
Each file is encoded in the printable characters (octal 40 through 176) of USASCII plus carriage 
return and linefeed. Each file consists of a sequence of variable-length lines. Each line is 
terminated by a carriage-return (octal 015) and line-feed (octal 012), or by just a line-feed. 

The information about a particular family and face at one size and orientation will be contained 
in one file. The file begins with information pertaining to the face as a whole, followed by the 
information and bitmaps for the individual characters. 

A font bitmap description file has the following general form, where each item is contained on 
a separate line of text in the file. Items on a line are separated by spaces. 

1. The word STARTFONT followed by a version number indicating the exact file 
format used. The version described here is number 2.1. 

2. One or more lines beginning with the word COMMENT. These lines may be ignored 
by any program reading the file. 

3. The word FONT followed by either the XLFD font name (as specified in the X 
Logical Font Description Conventions standard) or some private font name. 
Creators of private font name syntaxes are encouraged to register unique font name 
prefixes with the X Consortium to prevent naming conflicts. Note that the name 
continues all the way to the end of the line, and may contain spaces. 

4. The word SIZE followed by the point size of the characters, the x resolution, and 
the y resolution of the device for which these characters were intended. 

5. The word FONTBOUNDINGBOX followed by the width in x, height in y, and the x 
and y displacement of the lower left corner from the origin. (See the examples in 
section 3). 

6. Optionally the word STARTPROPERTIES followed by the number of properties (p) 
that follow. 

7. Then come p lines consisting of a word for the property name followed by either 
an integer or string surrounded by double-quote (octal 042). Internal double- 
quotes characters are indicated by using two in a row. 

8. Properties named FONT.ASCENT, FONTJDESCENT, and DEFAULT_CHAR should be 
provided to define the logical font-ascent and font-descent and the default-char for 
the font. These properties will be removed from the actual font properties in the 
binary form produced by a compiler. If these properties are not provided, a 
compiler may reject the font, or may compute (arbitrary) values for these 
properties. 

9. The property section, if it exists, is terminated by ENDPROPERTIES. 
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Bitmap Distribution Format 



10. The word CHARS followed by the number of character segments (c) that follow. 

1 1 . Then come c character segments of the form: 

a. The word STARTCHAR followed by up to 14 characters (no blanks) of 
descriptive name of the glyph. 

b. The word ENCODING followed by one of the following forms: 

i. <n> - the glyph index, i.e. a positive integer representing the 
character code used to access the glyph in X requests, as defined by 
the encoded character set given by the CHARSETJREGISTRY- 
CHARSET_ENCODING font properties for XLFD conforming 
fonts. If these XLFD font properties are not defined, then the 
encoding scheme is font-dependent; 

ii. -1 <n> - equivalent to form above. This syntax is provided for 
backwards compatibility with previous versions of this 
specification, and is not recommended for use with new fonts; 

iii. -1 - an unencoded glyph. Some font compilers may discard 
unencoded glyphs, but in general the glyph names may be used by 
font compilers and X servers to implement dynamic mapping of 
glyph repertoires to character encodings as seen through the X 
protocol. 

c. The word SWIDTH followed by the scalable width in x and y of character. 
Scalable widths are in units of l/1000fh of the size of the character. L c the 
size of the character is p points, the width information must be scaled by 
p/1000 to get the width of the character in printer's points. This width 
information should be considered as a vector indication the position of the 
next character's origin relative to the origin of this character. To convert 
the scalable width to the width in device pixels, multiply SWIDTH times 
p/1000 times r/72 where r is the device resolution in pixels per inch. The 
result is a real number giving the ideal print width in device pixels. The 
actual device width must of course be an integral number of device pixels 
and is given in the next entry. The SWIDTH y value should always be zero 
for a standard X font. 

d. The word DWIDTH followed by the width in x and y of the character in 
device units. Like the SWIDTH, this width information is a vector indicating 
the position of the next character's origin relative to the origin of this 
character. Note, that the DWIDTH of a given "hand-tuned" WYSIWYG 
glyph may deviate slightly from its ideal device-independent width given 
by SWIDTH in order to improve its typographic characteristics on a display. 
The DWIDTH y value should always be zero for a standard X font. 

e. The word BBX followed by the width in x (BBw), height in y (BBh) and x 
and y displacement (BBox, BBoy) of the lower left corner from the origin 
of the character. 

f. The optional word ATTRIBUTES followed by the attributes as 4 
hex-encoded characters. The interpretation of these attributes is undefined 
in this document. 

g. The word BITMAP. 
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h. h lines of hex-encoded bitmap, padded on the right with zero's to the 
nearest byte (i.e., multiple of 8). 

i. The word ENDCHAR. 

12. The file is terminated with the word ENDFONT. 

3. Metric Information 

Figures 3-1 and 3-2 best illustrate the bitmap format and character metric information. 
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. BBox 



BBw' 



BBoy 



BBh 



mmm 



BBw = 9, BBh = 22, BBox = -2, BBoy = -6 
DWIDTH = 80 
SWIDTH = 355 
"+" = character origin and width 

Figure 3-1: An example of a descender 
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— > 



BBox 



BBh 



BBoy 



BBw' 



+ + 



BBh = 6, BBw = 4, BBox = +2, BBoy = +12 
DWIDTH = 50 
SWIDTH = 223 

Figure 3-2: An example with the origin outside the bounding box 
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4. An Example File 

The following is an abbreviated example of a bitmap file containing the specification of two 
characters (the j and quoteright in 3). 1 

STARTFONT 2.1 

COMMENT This is a sample font in 2.1 format . 

FONT -Adobe-Helvetica-Bold-R-Normal — 24-240-75-75-P-65-ISO8859-1 
SIZE 24 75 75 

FONTBOUND INGBOX 9 24 -2 -6 
STARTPROPERTIES 19 
FOUNDRY "Adobe" 
FAMILY "Helvetica" 
WEIGHT_NAME "Bold" 
SLANT "R" 

SETWIDTH_NAME "Normal" 
ADD_STYLE_NAME "" 
PIXEL_SIZE 24 
POINT_SIZE 240 
RESOLUTION_X 75 
RESOLUTION_Y 75 
SPACING "P" 
AVERAGE_WIDTH 65 
CHARSET_REGISTRY "IS08859" 
CHARSET_ENCODING "1" 
MIN_SPACE 4 
FONT_ASCENT 21 
FONT_DESCENT 7 

COPYRIGHT "Copyright (c) 1987 Adobe Systems, Inc." 

NOTICE "Helvetica is a registered trademark of Linotype Inc. 

ENDPROPERTIES 

CHARS 2 

STARTCHAR j 

ENCODING 106 

SWIDTH 355 

DWIDTH 8 

BBX 9 22 -2 -6 

BITMAP 

0380 

0380 

0380 

0380 

0000 

0700 

0700 

0700 

0700 

0E00 

0E00 

0EO0 

0E00 

0E00 

1CO0 

1CO0 

1C00 

1C00 

2CO0 

7800 

F000 



'Helvetica® is a registered trademark of Allied Corporation. 
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EOOO 
ENDCHAR 

STARTCHAR quoteright 

ENCODING 39 

SWIDTH 223 

DWIDTH 5 

BBX 4 5 2 12 

ATTRIBUTES 01C0 

BITMAP 

70 

70 

60 

E0 

CO 

ENDCHAR 
ENDFONT 
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This appendix contains a copy of the document, X Logical Font Description Conventions, 
written by Jim Flowers at Digital Equipment Corporation. It is provided as a convenience 
for those who need to refer to the X font-name standard. Table 5-1 in Chapter 5 provides 
a summary of the X font-name format sufficient for interpreting the font names in the 
MacX Font Director window. 
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Version 1.3 
MIT X Consortium Standard 



Copyright © 1988 Massachusetts Institute of Technology, Cambridge, MA. 

Copyright © 1988, 1989 Digital Equipment Corporation, Maynard MA. All rights reserved. 

Permission to use, copy, modify, and distribute this documentation for any purpose and without fee is hereby 

granted, provided that the above copyright notice and this permission notice appear in all copies. MIT and Digital 

Equipment Corporation make no representations about the suitability for any purpose of the information in this 

document. This documentation is provided as is without express or implied warranty. 



X Window System is a trademark of M.I.T. 

Helvetica and Times are registered trademarks of Linotype Company. 

ITC Avant Garde Gothic is a registered trademark of International Typeface Corporation. 

Times Roman is a registered trademark of Monotype Corporation. 

Bitstream Amerigo is a registered trademark of Bitstream Inc. 

Stone is a registered trademark of Adobe Systems Inc. 
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3.1.2.13. CHARSETJREGISTRY : x-registered-name 7 

3.1.2.14. CHARSET_ENCODING : registered-name 8 

3.2. FontProperties 9 

3.2.1. FOUNDRY : ATOM 10 

3.2.2. FAMDLY_NAME : ATOM 10 

3.2.3. WEIGHT_NAME : ATOM 10 

3.2.4. SLANT : ATOM 10 

3.2.5. SETWIDTH.NAME : ATOM 10 

3.2.6. ADD_STYLE_NAME : ATOM 11 

3.2.7. PIXEL_SIZE : CARD32 11 

3.2.8. POINT_SIZE : CARD32 11 

3.2.9. RESOLUTION_X : CARD32 11 

3.2.10. RESOLUTION_Y : CARD32 11 

3.2.11. SPACING : ATOM 11 

3.2.12. AVERAGE_WIDTH : CARD32 12 
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3.2.13. CHARSET_REGISTRY : ATOM 12 

3.2.14. CHARSETJENCODING : ATOM 12 

3.2.15. MIN_SPACE : CARD32 12 

3.2.16. NORM_SPACE : CARD32 12 

3.2.17. MAX_SPACE : CARD32 12 

3.2.18. END_SPACE : CARD32 13 

3.2.19. AVG_CAPITAL_WIDTH : EMT32 13 

3.2.20. AVG_LOWERCASE_WIDTH : INT32 13 

3.2.21. QUAD_WIDTH : INT32 (DEPRECATED) 13 

3.2.22. FIGURE_WIDTH : INT32 13 

3.2.23. SUPERSCRIPT_X : INT32 14 

3.2.24. SUPERSCRIPT^ : INT32 14 

3.2.25. SUBSCRIPT_X : INT32 14 

3.2.26. SUBSCRIPT_Y : INT32 14 

3.2.27. SUPERSCRIPT_SIZE : CARD32 15 

3.2.28. SUBSCRIPT_SIZE : CARD32 15 

3.2.29. SMALLCAP_SIZE : CARD32 15 

3.2.30. UNDERLINE_POSITION : INT32 15 

3.2.31. UNDERLINE_THICKNESS : CARD32 15 

3.2.32. STRIKEOUT.ASCENT : INT32 16 

3.2.33. STRIKEOUTJDESCENT : INT32 16 

3.2.34. IT ALIC_ ANGLE : INT32 16 

3.2.35. CAP_HEIGHT : CARD32 16 

3.2.36. X_HEIGHT : CARD32 17 

3.2.37. RELATIVE_SETWIDTH : CARD32 17 

3.2.38. RELATIVE_WEIGHT : CARD32 18 

3.2.39. WEIGHT : CARD32 18 

3.2.40. RESOLUTION : CARD32 (DEPRECATED) 18 

3.2.41. FACE_NAME : ATOM 19 

3.2.42. COPYRIGHT : ATOM 19 

3.2.43. NOTICE : ATOM 19 

3.2.44. DESTINATION : CARD32 19 

4. Affected Elements of Xlib and the X Protocol 20 

5. BDF Conformance 20 

5.1. XLFD Conformance Requirements 20 

5.2. FONT_ASCENT, FONT_DESCENT and DEFAULT_CHAR 21 

5.2.1. FONT_ASCENT : INT32 21 

5.2.2. FONTJDESCENT : INT32 21 

5.2.3. DEFAULT_CHAR : CARD32 21 
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1. Introduction 

It is a requirement that X client applications must be portable across server implementations, 
with very different file systems, naming conventions, and font libraries. However, font access 
requests, as defined by the X Window System Protocol, Version 11, do not specify server- 
independent conventions for font names, nor provide adequate font properties for logically 
describing typographic fonts. 

X clients must be able to dynamically determine fonts available on any given server, in what 
sizes, styles, etc., so that understandable information can be presented to the user, or that intel- 
ligent font fallbacks can be chosen. It is desirable that the most common queries could be 
accomplished without the overhead of opening each font and inspection of font properties, i.e., 
through simple ListFonts requests. (E.g., if a user selected a Helvetica typeface family, a 
client application should be able to query the server for all Helvetica fonts and present only 
those setwidths, weights, slants, point sizes, character sets available for that family). 
This document gives a standard logical font description (XLFD) and conventions to be used in 
the X protocol so that clients can query and access screen type libraries in a consistent manner 
across all X servers. In addition to completely specifying a given font via its FontName, the 
XLFD also provides for a standard set of key FontProperties that describe the font in more 
detail. 

The XLFD provides an adequate set of typographic font properties, such as CAP_HEIGHT, 
X_HEIGHT, RELATIVE_SETWIDTH, for publishing and other applications to do intelligent font 
matching or substitution when handling documents created on some foreign server using poten- 
tially unknown fonts. In addition, this information is required by certain clients to automati- 
cally place subscripts, determine small capital heights, recommended leading, wordspace 
values, etc. 

Examples are for illustrative purposes only. 

2. Requirements and Goals 

This specification meets the short and long-term goals to have a standard logical font descrip- 
tion which: 

• provides unique, descriptive font names that support simple pattern matching; 

• supports multiple font vendors, arbitrary character sets and encodings; 

• is X server and operating/file system independent; 

• provides adequate descriptive font information for arbitrarily complex font 
matching/substitution; 

• is extensible. 

2.1. Unique, Descriptive Font Names 

It should be possible to have font names that are long enough and descriptive enough to have a 
reasonable probability of being unique without inventing a new registration organization. 
Resolution/size-dependent font masters, multi-vendor font libraries, etc., must be anticipated 
and handled by the font name alone. 

The name itself should be structured to be amenable to simple pattern matching and parsing, 
allowing X clients to restrict font queries to some subset of all possible fonts in the server. 

2.2. Support Multiple Font Vendors and Character Sets 

The font name and properties should distinguish between fonts that were supplied by different 
font vendors but that possibly share the same name. We anticipate a highly competitive font 
market where users will be able to buy fonts from a number of sources according to their par- 
ticular requirements. 
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A number of font vendors deliver each font with all glyphs designed for that font, where char- 
set mappings are defined by encoding vectors. Some server implementations may force these 
mappings to proprietary or standard charsets statically in the font data, while others may desire 
to perform the mapping dynamically in the server. Provisions must be made in the font name 
which allows a font request to specify/identify specific charset mappings in server environ- 
ments where multiple charsets are supported. 

2.3. Server, Operating and File System Independent 

X client applications that require a particular font should be able to use the descriptive name, 
without knowledge of the file system or other repository in use by the server. However, it 
should be possible for servers to translate a given font name into a file name syntax that it 
knows how to deal with, without compromising the uniqueness of the font name. This algo- 
rithm should be reversible (exactly how this translation is done is implementation dependent). 

2.4. Supports Arbitrarily Complex Font Matching/Substitution 

In addition to the font name, the XLFD should define a standard list of descriptive font proper- 
ties with agreed upon fallbacks for all fonts, so that client applications can derive font-specific 
formatting/display data, perform font matching/substitution when asked to handle potentially 
unknown fonts, as required. 

2.5. Extensible 

The XLFD must be extensible so that new and/or private descriptive font properties can be 
added to conforming fonts without obsoleting existing X client or server implementations. 

3. X Logical Font Description 

XLFD is divided into two basic components: the FontName, which gives all font information 
needed to uniquely identify a font in X protocol requests (e.g., OpenFont, ListFonts, etc.) and 
a variable list of optional FontProperties that describe a font in more detail. 
The FontName is used in font queries and returned as data in certain X protocol requests. 
The FontName is also specified as the data value for the FONT item in the X Consortium 
Character Bitmap Distribution Format specification (BDF V2.1). 

The FontProperties are supplied on a font-by-font basis, and are returned as data in certain X 
protocol requests as part of the XFontStruct data structure. The FontProperties names and 
associated data values may also appear as items of the 
STARTPROPERTIES...ENDPROPERTIES list in the BDF V2.1 specification. 

3.1. FontName 

The FontName is logically composed of two strings: a FontNameRegistry prefix, followed by 
a FontNameSuffix. The FontNameRegistry is an x-registered-name that identifies the regis- 
tration authority that owns the specified FontNameSuffix syntax and semantics. 

All font names that conform to this specification are to use a FontNameRegistry prefix 
defined to be the string i.e., ISO 8859-1 HYPHEN (Column/Row 02/13). All FontNam- 
eRegistry prefixes of the form ,l +version- , \ where version is the version of some future 
XLFD specification, are reserved by the X Consortium for future extensions to XLFD font 
names. If required, extensions to the current XLFD font name shall be constructed by append- 
ing new fields to the current structure, each delimited by the existing field delimiter. The avai- 
lability of other FontNameRegistry prefixes or fonts that support other registries is server 
implementation dependent. 

In the X protocol specification, the FontName is required to be a string; hence, numeric field 
values are represented in the name as string equivalents. All FontNameSuffix fields are also 
defined as FontProperties, in which case numeric property values are represented as signed or 
unsigned integers as appropriate. 
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3.1.1. FontName Syntax 

The FontName is a structured, parsable string (X data type STRING8) whose Backus-Naur 
Form syntax description is as follows: 

FontName ::= XFontNameRegistry XFontNameSuffix I PrivFontNameRegistry 
PrivFontNameSuffix 
XFontNameRegistry ::= XFNDelim I XFNExtPrefix Version XFNDelim 
XFontNameSuffix ::= FOUNDRY XFNDelim FAMILY_NAME XFNDelim WEIGHT_NAME 
XFNDelim SLANT XFNDelim SETWIDTH_NAME XFNDelim ADD_ 
STYLE_NAME XFNDelim PIXEL_SIZE XFNDelim POINT_SIZE 
XFNDelim RESOLUTION_X XFNDelim RESOLUTION_Y XFNDelim 
SPACING XFNDelim AVERAGE_WIDTH XFNDelim CHARSET_ 
REGISTRY XFNDelim CHARSET_ENCODING 
Version ::= STRING8 - the XLFD version that defines an extension to the font 
name syntax (e.g., "2.0") 
XFNExtPrefix ::= OCTET - the value of IS08859-1 PLUS (Column/Row 02/13) 
XFNDelim ::= OCTET - the value of IS08859-1 HYPHEN (Column/Row 02/13) 
PrivFontNameRegistry ::= STRING8 - other than those strings reserved by XLFD 
PrivFontNameSuffix ::= STRING8 

Field values are constructed as strings of IS08859-1 graphic characters, excluding the follow- 
ing: 

• HYPHEN (02/13), the XLFD font name delimiter character; 

• QUESTION MARK (03/15) and ASTERISK (02/10), the X protocol fontname wildcard 
characters. 

Alphabetic case distinctions are allowed, but are for human readability concerns only. Con- 
forming X servers will perform matching on font name query/open requests independent of 
case. The entire font name string must have no more than 255 characters. It is recommended 
that clients construct font name query patterns by explicitly including all field delimiters to 
avoid unexpected results. Note, that SPACE is a valid character of a FontName field; e.g., a 
FAMELY_NAME might be ITC Avant Garde Gothic. 

3.1.2. FontName Field Definitions 
3.1.2.1. FOUNDRY : x-registered-name 

FOUNDRY is an x-registered-name, the name or identifier of the digital type foundry that digi- 
tized and supplied the font data, or if different, the identifier of the organization that last 
modified the font shape or metric information. 

The reason this distinction is necessary is that a given font design may be licensed from one 
source (e.g., ITC) but digitized and sold by any number of different type suppliers. Each digi- 
tal version of the original design will in general be somewhat different in metrics and shape 
from the idealized original font data, as each font foundry, for better or for worse, has its own 
standards and practices for tweaking a typeface for a particular generation of output technolo- 
gies, or has its own perception of market needs. 

It is up to the type supplier to register with the X Consortium a suitable name for this 
FontName field, according to the registration procedures defined by the Consortium. 
The X Consortium shall define procedures for registering foundry names, and shall maintain 
and publish in a timely manner a registry of such registered names for use in XLFD font 
names and properties. 
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3.1.2.2. FAMILY_NAME : string 

FAMILY_NAME is a string that identifies the range or "family" of typeface designs that are 
all variations of one basic typographic style. This must be spelled out in full, with words 
separated by spaces as required. This name must be human-understandable and suitable for 
presentation to a font user to identify the typeface family. 

It is up to the type supplier to supply and maintain a suitable string for this field and font pro- 
perty, to secure the proper legal title to a given name, and to guard against the infringement of 
other's copyrights or trademarks. By convention, FAMILY_NAME is not translated. 
FAMILY_NAME may include an indication of design ownership if considered a valid part of 
the typeface family name (see examples below). 

Examples of FAMIL Y_N AMEs : 
Helvetica 

ITC Avant Garde Gothic 
Times 

Times Roman 
Bitstream Amerigo 
Stone 



3.1.2.3. WEIGHT_NAME : string 

WEIGHT_NAME is a string that identifies the font's typographic weight, i.e., the nominal 
blackness of the font, according to the FOUNDRY'S judgement. This name must be human- 
understandable and suitable for presentation to a font user. 

The interpretation of this field is somewhat problematic, as the typographic judgement of 
weight has traditionally depended on the overall design of the typeface family in question (i.e., 
it is possible that the DemiBold weight of one font could be almost equivalent in typographic 
feel to a Bold font from another family). 

WEIGHT_NAME is captured as an arbitrary string since it is an important part of a font's 
complete human-understandable name, but it should not be used for font matching/substitution. 
X client applications should use the weight-related font properties (RELATIVE_WEIGHT and 
WEIGHT) that give the coded relative weight, and the calculated weight, respectively, for this 
purpose. 

3.1.2.4. SLANT : code-string 

SLANT is a code-string that indicates the overall posture of the typeface design used in the 
font. The encoding is as follows: 



Code English Translation Description 



'R" 


Roman 


'I" 


Italic 


'0" 


Oblique 


'RI" 


Reverse Italic 


'RO" 


Reverse Oblique 


'OT" 


Other 



Upright design 

Italic design, slanted clockwise from vertical 
Obliqued upright design, slanted clockwise from verti- 
cal 

Italic design, slanted counter clockwise from vertical 
Obliqued upright design, slanted counter clockwise 
from vertical 
Other 



The SLANT codes are for programming convenience only, and usually are converted into their 
equivalent human-understandable form before being presented to a user. 
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3.1.2.5. SETWIDTH_NAME : string 

SETWIDTH_NAME is a string that gives the font's typographic proportionate width, i.e., the 
nominal width per horizontal unit of the font, according to the FOUNDRY'S judgment. 
As with WEIGHT_NAME, the interpretation of this field or font property is somewhat prob- 
lematic, as the designer's judgment of setwidth has traditionally depended on the overall design 
of the typeface family in question. X client applications should use the 
RELATIVE_SETWIDTH font property which gives the relative coded proportionate width, or 
calculate the proportionate width, for purposes of font matching or substitution. 

Examples of SETWIDTH_NAMEs: 

Normal 
Condensed 
Narrow 
Double Wide 

3.1.2.6. ADD_STYLE_NAME : string 

ADD_STYLE_NAME is a string that identifies additional typographic style information not 
captured by other fields, but needed to uniquely identify the font. 

ADD_STYLE_NAME is not a typeface classification field, and is only used for uniqueness. Its 
usage, as such, is not limited to typographic style distinctions. 
Examples of ADD_ST YLE_N AMEs : 

Serif 

Sans Serif 

Informal 

Decorated 

3.1.2.7. PIXEL.SIZE : integer-string 

PIXEL_SIZE is an unsigned integer-string typographic metric in device pixels which gives the 
body size of the font at a particular POINT_SIZE and RESOLUTION_Y. PIXEL_SIZE nor- 
mally incorporates additional vertical spacing considered part of the font design. (Note, how- 
ever, that this value is not necessarily equivalent to the height of the font bounding box). 
PIXEL_SIZE is in the range zero to a "very-large-number". 

PKEL_SIZE would normally be used by X client applications that need to query fonts accord- 
ing to device-dependent size, regardless of the point size or vertical resolution the font was 
designed for. 

3.1.2.8. POINT_SIZE : integer-string 

POINT_SIZE is an unsigned integer-string typographic metric in device-independent units 
which gives the body size the font was designed for. This field normally incorporates addi- 
tional vertical spacing considered part of the font design. (Note, however, that POINT_SIZE is 
not necessarily equivalent to the height of the font bounding box). POTNT_SIZE is expressed 
in decipoints (where points are as defined in the X protocol or 72.27 pts = 1 inch) in the range 
zero to a "very-large-number". 

POINT_SIZE and RESOLUTIONS would be used by X clients to query fonts according to 
device-independent size, to maintain constant text size on the display regardless of the 
PIXEL_SIZE used for the font. 
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3.1.2.9. RESOLUTIONJX : integer-string 

3.1.2.10. RESOLUTION_Y : integer-string 

RESOLUTION_X and RESOLUTION_Y are unsigned integer-strings, the horizontal and verti- 
cal resolution that the font was designed for, measured in pixels/dots per inch (dpi). Horizon- 
tal and vertical values are required since a separate bitmap font must be designed for displays 
with very different aspect ratios (e.g., 1:1, 4:3, 2:1, etc.). 

The separation of pixel/point size and resolution is necessary because X allows for servers with 
very different video characteristics (e.g., horizontal and vertical resolution, screen and pixel 
size, pixel shape, etc.) to potentially access the same font library. The font name, then, must 
differentiate between a 14 point font designed for 75 dpi (body size of about 14 pixels) or a 14 
point font designed for 150 dpi (about 28 pixels), etc. Further, in servers that implement some 
or all fonts as continuously scaled outlines, POINT_SIZE and RESOLUTION_Y will help the 
server to differentiate between potentially separate font masters for text, title, and display sizes 
or for other typographic considerations. 

3.1.2.11. SPACING : code-string 

SPACING is a code-string that indicates the escapement class of the font, i.e., monospace 
(fixed pitch), proportional (variable pitch), or charcell (a special monospaced font that con- 
forms to the traditional data processing character cell font model). 



Code English Translation Description 



"P" Proportional A font whose logical character widths vary for each glyph. Note 

that no other restrictions are placed on the metrics of a proportional 
font. 

"M" Monospaced A font whose logical character widths are constant (i.e., all char 

widths of the font are = max_bounds.width). No other restrictions 
are placed on the metrics of a monospaced font. 

"C" CharCell A monospaced font which follows the standard typewriter character 

cell model (i.e., the glyphs of the font can be modeled by X clients 
as "boxes" of the same width and height which are imaged side 
by side to form text strings, or top to bottom to form text lines. 
By definition, all glyphs have the same logical character width, and 
no glyphs have "ink" outside of the character cell-there is no 
kerning (i.e., on a per char basis with positive metrics: <= left- 
bearing <= right-bearing <= width; with negative metrics: width <= 
left-bearing <= right-bearing <= 0)-and the vertical extents of the 
font do not exceed the vertical spacing (i.e., on a per char basis: 
ascent <= font-ascent and descent <= font-descent). The cell height 
= font-descent + font-ascent, and width = AVERAGE_WIDTH. 



3.12.12. AVERAGE_WIDTH : integer-string 

AVERAGE_WIDTH is an unsigned integer-string typographic metric value giving the 
unweighted arithmetic mean width of all glyphs in the font, measured in l/10th pixels. Note, 
for monospaced and character cell fonts, this is the width of all glyphs in the font. 

3.1.2.13. CHARSET_REGISTRY : x-registered-name 
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3.1.2.14. CHARSETJENCODING : registered-name 

The character set used to encode the glyphs of the font (and implicitly the font's glyph reper- 
toire), as maintained by the X Consortium character set registry. CHARSETJREGISTRY is an 
x-registered-name that identifies the registration authority that owns the specified encoding. 
CHARSET_ENCODING is a registered-name that identifies the coded character set as defined 
by that registration authority. 

Although the X protocol does not explicitly have any knowledge about character set encodings, 
it is expected that server implementers will prefer to embed knowledge of certain proprietary or 
industry standard charsets into their font library for reasons of performance and convenience. 
The CHARSET_REGISTRY and CHARSET_ENCODING fields/properties allow an X client 
font request to specify a specific charset mapping in server environments where multiple char- 
sets are supported. The availability of any particular character set is font and server implemen- 
tation dependent. 

To prevent collisions when defining character set names, it is recommended that 
CHARSET_REGISTRY/CHARSET_ENCODING name pairs be constructed according to the 
following conventions: 



CharsetRegistry : 
CharsetEncoding : 
StdCharsetRegistryName : 
PrivCharsetRegistryName : 
StdCharsetEncodingName : 
PrivCharsetEncodingName : 
StdOrganizationld : 

StdNumber : 
Organizationld : 
Dot : 
Year : 



StdCharsetRegistryName I PrivCharsetRegistryName 

StdCharsetEncodingName I PrivCharsetEncodingName 

StdOrganizationld StdNumber I StdOrganizationld StdNumber Dot Year 

Organizationld STRING8 

STRING8-numeric part # of referenced standard 

STRING8 

STRING8-the registered name or acronym of the referenced standard 
organization 

STRING8-referenced standard number 
STRING8-the registered name or acronym of the organization 
"."-ISO 8859-1 FULL STOP (Column/Row 2/14) 
STRING8-numeric year (for example, 1989) 



The X Consortium shall maintain and publish in a timely manner a registry of such character 
set names for use in X protocol font names and properties as specified in XLFD. 
The ISO Latin 1 character set shall be registered by the X Consortium as the 
CHARSET_REGISTRY-CHARSET_ENCODING value pair: "IS08859-1". 

3.1.3. Examples 

The following examples of font names are derived from the screen fonts shipped with the R3 



Font 



X FontName 



75dpi Fonts 

Charter 12pt 
Charter Bold 12pt 
Charter Boldltalic 12pt 
Charter Italic 12pt 
Courier 8pt 
Courier lOpt 
Courier 12pt 
Courier 14pt 
Courier 18pt 
Courier 24pt 



-Bitstream-Charter-Medium-R-Normal-- 1 2- 1 20-75-75-P-68-ISO8859- 1 

-Bitstream-Charter-Bold-R-Normal- 1 2- 1 20-75-75-P-76-ISO8859- 1' 

-Bitstream-Charter-Bold-I-Normal- 1 2- 1 20-75-75-P-75-ISO8859- 1 C 

-Bitstream-Charter-Medium-I-Normal-12-120-75-75-P-66-ISO8859-l 

-Adobe-Courier-Medium-R-Normal~8-80-75-75-M-50-ISO8859-l 

-Adobe-Courier-Medium-R-Normal-10-100-75-75-M-60-ISO8859-l 

-Adobe-Courier-Medium-R-Normal-12-120-75-75-M-70-ISO8859-l 

-Adobe-Courier-Medium-R-Normal-14-140-75-75-M-90-ISO8859-l 

-Adobe-Courier-Medium-R-Normal-- 1 8- 1 80-75-75-M- 1 1 0-ISO8859- 1 

-Adobe-Courier-Medium-R-Normal-24-240-75-75-M-150-ISO8859-l 
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Font 



X FontName 



Courier Bold lOpt 
Courier BoldOblique lOpt 
Courier Oblique lOpt 



-Adobe- 
-Adobe- 
■Adobe- 



-Courier-Bold-R-Normal-- 1 0- 1 00-75-75-M-60-ISO8859- 1 
-Courier-Bold-O-Normal--10-100-75-75-M-60-ISO8859-l 
-Courier-Medium-O-Normal- 1 0- 100-75-75-M-60-ISO8859- 1 



100dpi Fonts 

Symbol 8pt 
Symbol lOpt 
Symbol 12pt 
Symbol 14pt 
Symbol 18pt 
Symbol 24pt 



-Adobe- 
-Adobe- 
-Adobe- 
■Adobe- 
■Adobe- 
■Adobe- 
-Adobe- 
-Adobe- 
•Adobe- 
-Adobe- 



-Symbol-Medium-R-Normal- 1 1 -80- 1 00- 1 00-P-6 1 -Adobe-FONTSPECIFIC 
-Symbol-Medium-R-Normal- 1 4- 1 00- 1 00- 1 00-P-85- Adobe-FONTSPECIFIC 
-Symbol-Medium-R-Normal-- 1 7- 1 20- 1 00- 1 00-P-95- Adobe-FONTSPECIFIC 
-Symbol-Medium-R-NormaI-20- 1 40- 1 00- 1 00-P- 1 07- Adobe-FONTSPECIFIC 
-Symbol-Medium-R-Normal-25- 1 80- 1 00- 1 00-P- 1 42- Adobe-FONTSPECIFIC 
-Symbol-Medium-R-Normal -34-240- 1 00- 1 00-P- 1 9 1 - Adobe-FONTSPECIFIC 
-Times-Bold-R-Normal- 14- 1 00-1 00- 1 00-P-76-ISO8859- 1 



Times Bold lOpt 
Times Boldltalic lOpt 
Times Italic lOpt 
Times Roman lOpt 



-Times-Bold-I-Normal- 1 4- 1 00- 1 00- 1 00-P-77-ISO8859- 1 
-Times-Medium-I-Normal- 1 4- 1 00- 1 00- 1 00-P-73-ISO8859- 1 
-Times-Medium-R-Normal- 14- 1 00- 1 00- 1 00-P-74-ISO8859- 1 



3.2. FontProperties 

All font properties are optional, but will generally include the font name fields, and on a font- 
by-font basis any other useful font descriptive/usage information that may be required to use 
the font intelligently. The XLFD specifies an extensive set of standard X font properties, their 
interpretation and fallback rules when the property is not defined for a given font. The goal is 
to provide client applications with enough font information to be able to make automatic 
formatting/display decisions with good typographic results. 

Additional standard X font property definitions may be defined in the future and private pro- 
perties may exist in X fonts at any time. Private font properties should be defined to conform 
to the general mechanism defined in the X protocol to prevent overlap of name space and 
ambiguous property names, i.e., private font property names are of the form: IS08859-1 
UNDERSCORE (Column/Row 05/15), followed by the organizational identifier, followed by 
UNDERSCORE, and terminated with the property name. 
The Backus-Naur Form syntax description of X Font Properties is: 

Properties ::= OptFontPropList 

OptFontPropList ::= NULL I OptFontProp OptFontPropList 

OptFontProp ::= PrivateFontProp I XFontProp 

PrivateFontProp ::= STRING8 I Underscore Organizationld Underscore STRING8 
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XFontProp ::= FOUNDRY I FAMILY_NAME I WEIGHTJMAME I SLANT 1 
SETWIDTHLNAME I ADD_STYLE_NAME I PIXEL_SIZE I 
POINT_SIZE I RESOLUTION_X I RESOLUTION_Y I SPACING I 
AVERAGE_WIDTH I CHARSET_REGISTRY I 
CHARSET_ENCODING 1 QUAD_WIDTH I RESOLUTION I 
MIN_SPACE I NORM_SPACE I MAX_SPACE I END_SPACE I 
SUPERSCRIPT_X I SUPERSCRIPT_Y I SUBSCRIPT.X I 
SUBSCRIPT_Y I UNDERLINE_POSITION I 
UNDERLINE_THICKNESS I STRIKEOUT_ASCENT I 
STRIKEOUT_DESCENT I ITALIC_ANGLE I X_HEIGHT I WEIGHT I 
FACE_NAME I COPYRIGHT I AVG_CAPITAL_WIDTH I 
AVG_LOWERCASE_WIDTH I RELATIVE_SETWIDTH I 
RELATIVE_WEIGHT I CAP_HEIGHT I SUPERSCRIPT_SIZE I 
FIGURE_WIDTH I SUBSCRIPT_SIZE I SMALL_CAP_SIZE I 
NOTICE I DESTINATION 
Underscore ::= OCTET-the value of IS08859-1 UNDERSCORE character 
(Column/Row 05/15) 
Organization^ ::= STRING8-the registered name of the organization 



3.2.1. FOUNDRY : ATOM 

As defined in the FontName, except the property type is ATOM. 

FOUNDRY can not be calculated or defaulted if not supplied as a font property. 

3.2.2. FAMILY_NAME : ATOM 

As defined in the FontName, except the property type is ATOM. 

FAMILY_NAME can not be calculated or defaulted if not supplied as a font property. 

3.2.3. WEIGHT_NAME : ATOM 

As defined in the FontName, except the property type is ATOM. 
WEIGHT_NAME can be defaulted if not supplied as a font property, as follows: 

if (WEIGHT_NAME undefined) then 
WEIGHT.NAME = ATOM("Medium") 

3.2.4. SLANT : ATOM 

As defined in the FontName, except the property type is ATOM. 
SLANT can be defaulted if not supplied as a font property, as follows: 

if (SLANT undefined) then 
SLANT = ATOM("R") 

3.2.5. SETWIDTH_NAME : ATOM 

As defined in the FontName, except the property type is ATOM. 
SETWIDTH_NAME can be defaulted if not supplied as a font property, as follows: 

if (SETWIDTH_NAME undefined) then 
SETWIDTH_NAME = ATOM("Normal") 
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3.2.6. ADD_STYLE_NAME : ATOM 

As denned in the FontName, except the property type is ATOM. 
ADD_STYLE_NAME can be defaulted if not supplied as a font property, as follows: 

if (ADD_STYLE_NAME undefined) then 
ADD_STYLE_NAME = ATOM("") 

3.2.7. PIXEL_SIZE : CARD32 

As defined in the FontName, except the property type is CARD32. 

X clients requiring pixel values for the various typographic fixed spaces (EM space, EN space 
and THIN space), can use the following algorithm for computing these values from other pro- 
perties specified for a font: 

DeciPointsPerlnch = 722.7 

EMspace = ROUND ((RESOLUTION_X * POINT_SIZE) / DeciPointsPerlnch) 
ENspace = ROUND (EMspace / 2) 
THINspace = ROUND (EMspace / 3) 

Note that a "/" denotes real division, "*" denotes real multiplication, and "ROUND" 
denotes a function that rounds its real argument "a" up/down to the next integer, according to 
x = FLOOR(a + 0.5), where FLOOR is a function that rounds its argument down to an integer. 

PIXEL_SIZE can be approximated if not supplied as a font property, according to the algo- 
rithm: 

DeciPointsPerlnch = 722.7 

if (PIXEL_SIZE undefined) then 

PIXEL_SIZE = ROUND ((RESOLUTION_Y * POINT_SIZE) / DeciPointsPerlnch) 

3.2.8. POINT_SIZE : CARD32 

As defined in the FontName, except the property type is CARD32. 

X clients requiring device-independent values for EMspace, ENspace and THINspace, can use 
the following algorithm: 

EMspace = ROUND (POINT_SIZE / 10) 
ENspace = ROUND (POINTJSIZE / 20) 
THINspace = ROUND (POINTJSIZE / 30) 

Design POINT_SIZE can not be calculated or approximated. 

3.2.9. RESOLUTION_X : CARD32 

As defined in the FontName, except the property type is CARD32. 
RESOLUTION_X cannot be calculated or approximated. 

3.2.10. RESOLUTION_Y : CARD32 

As defined in the FontName, except the property type is CARD32. 
RESOLUTION_Y cannot be calculated or approximated. 

3.2.11. SPACING : ATOM 

As defined in the FontName, except the property type is ATOM. 

SPACING can be calculated if not supplied as a font property, according to the definitions 
given above for the FontName. 
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3.2.12. AVERAGE_WIDTH : CARD32 

As defined in the FontName, except the property type is CARD32. 

AVERAGE_WIDTH can be calculated if not provided as a font property, according to the fol- 
lowing algorithm: 

if (AVERAGE_WIDTH undefined) then 

AVERAGE_WIDTH = ROUND (MEAN (all glyph widths in font) * 10) 

where MEAN is a function that returns the arithmetic mean of its arguments. 

X clients requiring values for the number of characters per inch (pitch) of a monospaced font 

can use the following algorithm using the AVERAGEJWIDTH and RESOLUTION_X font 

properties: 

if (SPACING not proportional) then 

CharPitch = (RESOLUTION_X * 10) / AVERAGEJWIDTH 

3.2.13. CHARSET_REGISTRY : ATOM 

As defined in the FontName, except the property type is ATOM. 
CHARSET_REGISTRY can not be defaulted if not supplied as a font property. 

3.2.14. CHARSET_ENCODING : ATOM 

As defined in the FontName, except the property type is ATOM. 
CHARSET_ENCODING can not be defaulted if not supplied as a font property. 

3.2.15. MIN_SPACE : CARD32 

MIN_SPACE is an unsigned integer value that gives the recommended minimum wordspace 
value to be used with this font. 

MIN_SPACE can be approximated if not provided as a font property, according to the algo- 
rithm: 

if (MINJSPACE undefined) then 
MIN_SPACE = ROUND(0.75 * NORM_SPACE) 

3.2.16. NORM_SPACE : CARD32 

NORM_SPACE is an unsigned integer value that gives the recommended normal wordspace 
value to be used with this font. 

NORM_SPACE can be approximated if not provided as a font property, according to the fol- 
lowing algorithm: 

DeciPointsPerlnch = 722.7 
if (NORM_SPACE undefined) then 
if (SPACE glyph exists) then 

NORM_SPACE = width of SPACE 
else NORM_SPACE = ROUND((0.33 * RESOLUTION_X * POINTJSIZE) / 
DeciPointsPerlnch) 

3.2.17. MAX_SPACE : CARD32 

MAX_SPACE is an unsigned integer value that gives the recommended maximum wordspace 
value to be used with this font. 

MAX_SPACE can be approximated if not provided as a font property, according to the follow- 
ing algorithm: 
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if (MAX_SPACE undefined) then 

MAX_SPACE = ROUND(1.5 * NORM_SPACE) 

3.2.18. END_SPACE : CARD32 

END_SPACE is an unsigned integer value that gives the recommended spacing at the end of 
sentences. 

END_SPACE can be approximated if not provided as a font property, according to the follow- 
ing algorithm: 

if (END_SPACE undefined) then 
END_SPACE = NORM_SPACE 

3.2.19. AVG_CAPITAL_WIDTH : INT32 

AVG_CAPITAL_WIDTH is an integer value that gives the unweighted arithmetic mean width 
of all the capital glyphs in the font, in l/10th pixels (applies to Latin and non-Latin fonts). For 
Latin fonts, capitals are the glyphs A-Z. Normally used for font matching/substitution. 

AVG_CAPITAL_WIDTH can be calculated if not provided as a font property, according to the 
following algorithm: 

if (AVG_CAPITAL_WIDTH undefined) then 
AVG_CAPITAL_WIDTH = ROUND (MEAN (capital glyph widths) * 10) 

Note that MEAN is a function that returns the arithmetic mean of its arguments. 

3.2.20. AVG_LOWERCASE_WIDTH : INT32 

AVG_LOWERCASE_WIDTH is an integer value that gives the unweighted arithmetic mean 
width of all the lower case glyphs in the font in l/10th pixels. For Latin fonts, lower case are 
the glyphs a-z. Normally used for font matching or substitution. 

Where appropriate, AVG_LOWERCASE_WIDTH can be approximated if not provided as a 
font property, according to the following algorithm: 

if (AVG_LOWERCASE_WIDTH undefined) then 
if (lower case exists) then 

AVG_LOWERCASE_WIDTH = ROUND (MEAN (lower case glyph widths) * 10) 
else AVG_LOWERCASE_WIDTH undefined 

3.2.21. QUAD_WIDTH : INT32 (DEPRECATED) 

QUAD_WIDTH was incorrectly defined in the X protocol, and is redundant since all typo- 
graphic fixed spaces (EM, EN and THIN) are constant for a given font size (i.e., they do not 
vary according to setwidth). X clients requiring these properties are encouraged to discontinue 
usage of QUAD_WIDTH and compute these values from other font properties. X clients 
requiring a font-dependent width value should use either the FIGUREJWIDTH or one of the 
average character width font properties (AVERAGE_WIDTH, AVG_CAPITAL_WIDTH or 
AVG_LOWERCASE_WIDTH) for this purpose. 

See also PIXEL_SIZE, FIGURE_WIDTH, AVERAGE_WIDTH, AVG_CAPITAL_WIDTH 
and AVG_LOWERCASE_WIDTH font property definitions. 

3.2.22. FIGURE_WIDTH : INT32 

FIGURE_WIDTH is an integer typographic metric that gives the width of the tabular figures 
and the dollar sign, if suitable for tabular setting (all widths equal). For Latin fonts, these 
tabular figures are the arabic numerals 0-9. 
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FIGUREJWIDTH can be approximated if not supplied as a font property, according to the fol- 
lowing algorithm: 

if (numerals and DOLLAR sign are defined & widths are equal) then 

FIGURE.WIDTH = width of DOLLAR 
else FIGURE_WIDTH property undefined 

3.2.23. SUPERSCRIPTS : INT32 

SUPERSCRIPT_X is an integer value that gives the recommended horizontal offset in pixels 
from the position point to the X origin of synthetic superscript text. If the current position 
point is at [X,Y], then superscripts should begin at [X + SUPERSCRIPTS, Y - 
SUPERSCRIPTS]. 

SUPERSCREPT_X can be approximated, if not provided as a font property, according to the 
following algorithm: 

if (SUPERSCRIPTS undefined) then 

if (TANGENT(ITALIC_ANGLE) defined) then 

SUPERSCRIPTS = ROUND((0.40 * CAP_HEIGHT) / TANGENT(ITALIC_ANGLE)] 
else SUPERSCRIPTS = ROUND(0.40 * CAP_HEIGHT) 

Note that TANGENT is a trigonometric function that returns the tangent of its argument (in 
degrees scaled by 64). 

3.2.24. SUPERSCRIPTS : INT32 

SUPERSCRIPT_Y is an integer value that gives the recommended vertical offset in pixels 
from the position point to the Y origin of synthetic superscript text. If the current position 
point is at [X,Y], then superscripts should begin at [X + SUPERSCRIPTS Y - 
SUPERSCRIPT_Y]. 

SUPERSCRIPT_Y can be approximated, if not provided as a font property, according to the 
following algorithm: 

if (SUPERSCRIPT_Y undefined) then 

SUPERSCRIPTS = ROUND(0.40 * CAP_HEIGHT) 

3.2.25. SUBSCRIPTS : INT32 

SUBSCRIPT_X is an integer value that gives the recommended horizontal offset in pixels from 
the position point to the X origin of synthetic subscript text. If the current position point is at 
[X,Y], then subscripts should begin at [X + SUBSCRIPT_X, Y + SUBSCRIPTS]. 

SUBSCRIPTS can be approximated, if not provided as a font property, according to the fol- 
lowing algorithm: 

if (SUBSCRIPTS undefined) then 

if (TANGENT(ITALIC_ANGLE) defined) then 

SUBSCRIPTS = ROUND((0.40 * CAP_HEIGHT) / TANGENT(ITALIC_ANGLE)) 
else SUBSCRIPTS = ROUND(0.40 * CAP_HEIGHT) 

3.2.26. SUBSCRIPT_Y : INT32 

SUBSCRIPTS is an integer value that gives the recommended vertical offset in pixels from 
the position point to the Y origin of synthetic subscript text. If the current position point is at 
[X,Y], then subscripts should begin at [X + SUBSCRIPTS, Y + SUBSCRIPTS]- 
SUBSCRIPTS can be approximated, if not provided as a font property, according to the fol- 
lowing algorithm: 
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if (SUBSCRIPT_Y undefined) then 

SUBSCRIPT_Y = ROUND(0.40 * CAP_HEIGHT) 

3.2.27. SUPERSCRIPT_SIZE : CARD32 

SUPERSCRIPT_SIZE is an unsigned integer value that gives the recommended body size of 
synthetic superscripts to be used with this font, in pixels. Note that this will generally be 
smaller than the size of the current font; i.e., superscripts are imaged from a smaller font, 
offset according to SUPERSCRIPT_X and SUPERSCRIPT^. 

SUPERSCRIPT_SIZE can be approximated if not provided as a font property, according to the 
following algorithm: 

if (SUPERSCRIPT_SIZE undefined) then 

SUPERSCRIPT_SIZE = ROUND(0.60 * PIXEL.SIZE) 

3.2.28. SUBSCRIPT_SIZE : CARD32 

SUBSCRIPT_SIZE is an unsigned integer value that gives the recommended body size of syn- 
thetic subscripts to be used with this font, in pixels. As with SUPERSCRIPT_SIZE, this will 
generally be smaller than the size of the current font; i.e., subscripts are imaged from a smaller 
font, offset according to SUBSCRIPT_X and SUBSCRIPT_Y. 

SUBSCRIPT_SIZE can be approximated if not provided as a font property, according to the 
algorithm: 

if (SUBSCRIPTJSIZE undefined) then 

SUBSCRIPT_SIZE = ROUND(0.60 * PIXEL_SIZE) 

3.2.29. SMALL_CAP_SIZE : CARD32 

SMALL_CAP_SIZE is an integer value that gives the recommended body size of synthetic 
small capitals to be used with this font, in pixels. Small capitals are generally imaged from a 
smaller font, of slightly more weight. No offset [X,Y] is necessary. 

SMALL_CAP_SIZE can be approximated if not provided as a font property, according to the 
following algorithm: 

if (SMALL_CAP_SIZE undefined) then 

SMALL_CAP_SIZE = ROUND(PIXEL_SIZE * ((XJHEIGHT 

+ ((CAP_HEIGHT - XJHEIGHT) / 3)) / CAP_HEIGHT)) 

3.2.30. UNDERLINE_POSITION : INT32 

UNDERLINE_POSITION is an integer value that gives the recommended vertical offset in 
pixels from the baseline to the top of the underline. If the current position point is at [X,Y], 
the top of the baseline is given by [X, Y + UNDERLINE_POSITION]. 

UNDERLINE_POSITION can be approximated if not provided as a font property, according to 
the following algorithm: 

if (UNDERLINE_POSITION undefined) then 
UNDERLINE_POSITION = ROUND(max_bounds.descent / 2) 

3.2.31. UNDERLINE_THIC KNESS : CARD32 

UNDERLINE_POSITION is an unsigned integer value that gives the recommended underline 
thickness, in pixels. 
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UNDERLINE_THICKNESS can be approximated if not provided as a font property, according 
to the following algorithm: 

CapStem Width = average width of the stems of capitals 
if (UNDERLINE_THICKNESS undefined) then 
UNDERLINEJTHICKNESS = CapStemWidth 

3.2.32. STRIKEOUT_ASCENT : INT32 

STRIKEOUT_ASCENT is an integer value that gives the vertical ascent for boxing or voiding 
glyphs in this font. If the current position is at [X,Y] and the string extent is EXTENT, the 
upper-left comer of the strikeout box is at [X, Y - STRIKEOUT_ASCENT] and the lower- 
right comer of the box is at [X + EXTENT, Y + STRIKEOUTJDESCENT]. 

STRIKEOUT_ASCENT can be approximated if not provided as a font property, according to 
the following algorithm: 

if (STRIKEOUT_ASCENT undefined) 

STRIKEOUT_ASCENT = max_bounds.ascent 

3.2.33. STRIKEOUT_DESCENT : INT32 

STRIKEOUT_DESCENT is an integer value that gives the vertical descent for boxing or void- 
ing glyphs in this font. If the current position is at [X,Y] and the string extent is EXTENT, 
the upper-left corner of the strikeout box is at [X, Y - STRIKEOUT, AS CENT] and the 
lower-right comer of the box is at [X + EXTENT, Y + STRIKEOUTJDESCENT]. 

STRIKEOUTJDESCENT can be approximated if not provided as a font property, according to 
the following algorithm: 

if (STRIKEOUTJDESCENT undefined) 

STRIKEOUTJDESCENT = max_bounds.descent 

3.2.34. ITALIC_ANGLE : INT32 

ITALIC_ANGLE is an integer value that gives the nominal posture angle of the typeface 
design, in 1/64 degrees, measured from the glyph origin counterclockwise from the three 
o'clock positon. 

ITALIC_ANGLE can be defaulted if not provided as a font property, according to the follow- 
ing algorithm: 

if (ITALIC_ANGLE undefined) then 
ITALIC_ANGLE = (90 * 64) 

3.2.35. CAPJ3EIGHT : CARD32 

CAP_HEIGHT is an unsigned integer, the nominal height of the capital letters contained in the 
font, as specified by the FOUNDRY or typeface designer. Where applicable, it is defined to 
be the height of the Latin upper case letter X. 

CAP_HEIGHT is required by certain clients to compute scale factors and positioning offsets 
for algorithmically generated glyphs where this information or designed glyphs are not expli- 
citly provided by the font (e.g., small capitals, superiors, inferiors, etc.). Capital height is also 
a critical factor in font matching and substitution. 

CAP_HEIGHT can be approximated if not provided as a font property, according to the fol- 
lowing algorithm: 
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if (CAP_HEIGHT undefined) then 
if (Latin font) then 

CAP_HEIGHT = XCharStruct.ascentfglyph X] 
else if (capitals exist) then 

CAP_HEIGHT = XCharStruct.ascent[some capital glyph] 
else CAPJHEIGHT undefined 

3.2.36. X_HEIGHT : CARD32 

X_HEIGHT is a unsigned integer, the nominal height above the baseline of the lower case 
glyphs contained in the font, as specified by the FOUNDRY or typeface designer. Where 
applicable, it is defined to be the height of the Latin lower case letter x. 

As with Capital height, X_HEIGHT is required by certain clients to compute scale factors for 
algorithmically generated small capitals, where not explicitly provided by the font resource and 
is a critical factor in font matching and substitution. 

X_HEIGHT can be approximated if not provided as a font property, according to the following 
algorithm: 

if (XJHEIGHT undefined) then 
if (Latin font) then 

X_HEIGHT = XCharStruct.ascentfglyph x] 
else if (lower case exists) then 

X_HEIGHT - XCharStruct.ascent[some lower case glyph] 
else XJHEIGHT is undefined 



3.2.37. RELATIVE_SETWIDTH : CARD32 

RELATIVE_SETWIDTH is an integer that gives the coded proportionate width of the font, 
relative to all known fonts of the same typeface family, according to the type designer's or 
FOUNDRY'S judgement. 



The possible values are: 


Code 


English String 


Description 





undefined 


Undefined or unknown 


10 


UltraCondensed 


Lowest ratio of average width to height 


20 


ExtraCondensed 




30 


Condensed 


Condensed, Narrow, Compressed, ... 


40 


SemiCondensed 




50 


Medium 


Medium, Normal, Regular, ... 


60 


SemiExpanded 


SemiExpanded, DemiExpanded, ... 


70 


Expanded 




80 


ExtraExpanded 


ExtraExpanded, Wide, ... 


90 


UltraExpanded 


Highest ratio of average width to height 



RELATIVE_SETWIDTH can be defaulted if not provided as a font property, according to the 
following algorithm: 

if (RELATIVE_SETWIDTH undefined) then 
RELATTVE_SETWIDTH = 50 

X clients that wish to obtain a calculated proportionate width of the font (i.e., a font- 
independent way of identifying the proportionate width across all fonts and all font vendors) 
can use the following algorithm: 
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SETWIDTH = AVG_CAPITAL_WIDTH / (CAPJHEIGHT * 10) 
Note that SETWIDTH is a real with being the "narrowest" calculated setwidth. 
3.2.38. RELATIVE_WEIGHT : CARD32 

RELATIVE_WEIGHT is an integer that gives the coded weight of the font, relative to all 
known fonts of the same typeface family, according to the type designer's or FOUNDRY'S 
judgement. 



The possible values are: 


Code 


English String 


Description 





undefined 


Undefined or unknown 


10 


UltraLight 


Lowest ratio of stem width to height 


20 


ExtraLight 




30 


Light 




40 


SemiLight 


SemiLight, Book, ... 


50 


Medium 


Medium, Normal, Regular,... 


60 


SemiBold 


SemiBold, DemiBold, ... 


70 


Bold 




80 


ExtraBold 


ExtraBold, Heavy, ... 


90 


UltraBold 


UltraBold, Black, the highest ratio of stem width to 






height 



RELATIVE_WEIGHT can be defaulted if not provided as a font property, according to the 
following algorithm: 

if (RELATIVE_WEIGHT undefined) then 
RELATIVEJWEIGHT - 50 



3.2.39. WEIGHT : CARD32 

Calculated WEIGHT is an unsigned integer, the calculated weight of the font, computed as the 
ratio of capital stem width to CAPJHEIGHT, in the range to 1000, where zero is the "light- 
est" weight. 

WEIGHT can be calculated if not supplied as a font property, according to the following algo- 
rithm: 

CapStem Width = average width of the stems of capitals 
if (WEIGHT undefined) then 
WEIGHT = ROUND ((CapStemWidth * 1000) / CAPJHEIGHT) 

A calculated value for weight is necessary when matching fonts from different families because 
both the RELATIVEJWEIGHT and the WEIGHT JSIAME are assigned by the typeface sup- 
plier, according to its tradition and practice, and therefore somewhat subjective. Calculated 
WEIGHT provides a font-independent way of identifying the weight across all fonts and all 
font vendors. 

3.2.40. RESOLUTION : CARD32 (DEPRECATED) 

Independent horizontal and vertical design resolution components are required to accomodate 
displays with nonsquare aspect ratios and are given by the RESOLUTIONJX and 
RESOLUTIONJY font name fields/properties. The units of the original definition of RESOLU- 
TION are also in conflict with these new properties. X clients are encouraged to discontinue 
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usage of RESOLUTION and to use the appropriate X,Y resolution properties as required. 

3.2.41. FACE_NAME : ATOM 

FACE_NAME is a human-understandable string that gives the full device-independent typeface 
name, including the owner, weight, slant, set, etc., but not the resolution, size, etc. Normally 
used as feedback during font selection. 

FACE_NAME can not be calculated or approximated if not provided as a font property. 

3.2.42. COPYRIGHT : ATOM 

COPYRIGHT is a human-understandable string that gives the copyright information of the 
legal owner of the digital font data. 

This information is a required component of a font but is independent of the particular format 
used to represent it (i.e., it cannot be captured as a comment that could later be "thrown 
away" for efficiency reasons). 

COPYRIGHT can not be calculated or approximated if not provided as a font property. 

3.2.43. NOTICE : ATOM 

NOTICE is a human-understandable string that gives the copyright information of the legal 
owner of the font design, or if not applicable, the trademark information for the typeface 
FAMILY_NAME. 

Typeface design and trademark protection laws vary from country to country, the USA having 
no design copyright protection currently, while various countries in Europe offer both design 
and typeface family name trademark protection. As with COPYRIGHT, this information is a 
required component of a font but is independent of the particular format used to represent it. 
NOTICE can not be calculated or approximated if not provided as a font property. 

3.2.44. DESTINATION : CARD32 

DESTINATION is an unsigned integer code that gives the font design destination, i.e., whether 
it was designed as a screen proofing font to match printer font glyph widths (WYSIWYG), as 
an optimal video font (possibly with corresponding printer font) for extended screen viewing 
(VideoText), etc. 

The font design considerations are very different, and at current display resolutions, the reada- 
bility and legibility of these two kinds of screen fonts are very different. DESTINATION 
allows publishing clients that use X to model the printed page, and Video Text clients such as 
on-line documentation browsers, to query for X screen fonts that suit their particular require- 
ments. 

The encoding is as follows: 



Code 


English String 


Description 





WYSIWYG 


A font optimized to match the typographic design and 






metrics of an equivalent printer font 


1 


Video Text 


A font optimized for screen legibility and readability 



3.3. Built-in Font Property Atoms 

The following font property atom definitions were predefined in the initial Version 1 1 of the X 
protocol: 

Font Property Property Type 
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Font Property Property Type 



MIN_SPACE 


CARD32 


NORM_SPACE 


CARD32 


MAX_SPACE 


CARD32 


END_SPACE 


CARD32 


SUPERSCRIPT_X 


INT32 


SUPERSCRIPT_Y 


INT32 


CT TT> O/^Tl TTyT 1 "V 

S U BSCRIFI _X 


INI 32 


SUBSCRIPT_Y 


INT32 


UNDERLINE_POSITION 


INT32 


UNDERLINE_THICKNESS 


CARD32 


STRIKEOUT_ASCENT 


INT32 


STRIKEOUT_DESCENT 


INT32 


FONT ASCENT 


INT32 


FONT DESCENT 


INT32 


ITALIC ANGLE 


INT32 


X HEIGHT 


INT32 


QUAD WIDTH 


INT32 - deprecated 


WEIGHT 


CARD32 


POINT SIZE 


CARD32 


RESOLUTION 


CARD32 - deprecated 


COPYRIGHT 


ATOM 


FACE_NAME 


ATOM 


FAMILY NAME 


ATOM 


DEFAULT CHAR 


CARD32 



4. Affected Elements of Xlib and the X Protocol 

The following X protocol requests must use the font naming conventions: 

• OpenFont - for the name parameter 

• ListFonts - for the pattern parameter 

• ListFontsWithlnfo - for the pattern parameter 

In addition, the following Xlib functions must use the font naming conventions: 

• XLoadFont - for the name parameter 

• XListFontsWithlnfo - for the pattern parameter 

• XLoadQueryFont - for the name parameter 

• XListFonts - for the pattern parameter 

5. BDF Conformance 

The bitmap font distribution and interchange format adopted by the X Consortium (BDF V2.1) 
provides a general mechanism for identifying the font name of an X font and a variable list of 
font properties, but does not mandate the syntax/semantics of the font name or the semantics of 
the font properties that might be provided in a BDF font. This section identifies the require- 
ments for BDF fonts that conform to XLFD. 

5.1. XLFD Conformance Requirements 

A BDF font conforms to the XLFD VI. 3 specification if and only if the following conditions 
are satisfied: 
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• the value for the BDF item FONT conforms to the syntax and semantic definition of a 
XLFD FontName string; 

• the FontName begins with the X FontNameRegistry prefix: 

• all XLFD FontName fields are defined; 

• any FontProperties provided conform in name and semantics to the XLFD FontProper- 
ties definitions. 

A simple method of testing for conformance would entail first verifying that the FontNameRe- 
gistry prefix is the string that the number of field delimiters in the string and coded field 
values are valid, and that each font property name either matches a standard XLFD property 
name or follows the definition of a private property. 

5.2. FONT_ASCENT, FONTJDESCENT and DEFAULT_CHAR 

FONT_ASCENT, FONT_DESCENT and DEFAULT_CHAR are provided in the BDF 
specification as properties that are moved to the XFontStruct by the BDF font compiler in 
generating the X server-specific binary font encoding. If present, these properties shall comply 
with the following semantic definitions. 

5.2.1. FONT_ASCENT : INT32 

FONT_ASCENT is an unsigned integer that gives the recommended typographic ascent above 
the baseline, for determining interline spacing. Specific glyphs of the font may extent beyond 
this. If the current position point for line n is at [X,Y], then the origin of the next line n+1 
(allowing for a possible font change) is [X, Y + FONTJDESCENT + FONT_ASCENT y ]. 

FONT_ASCENT can be approximated if not provided as a font property, according to the fol- 
lowing algorithm: 

if (FONT_ASCENT undefined) then 
FONT_AS CENT = maxjoounds.ascent 

5.2.2. FONT_DESCENT : INT32 

FONT_DESCENT is an unsigned integer that gives the recommended typographic descent 

below the baseline, for determining interline spacing. Specific glyphs of the font may extent 

beyond this. If the current position point for line n is at [X,Y], then the origin of the next line 

n+1 (allowing for a possible font change) is [X, Y + FONTJDESCENT + FONT_ASCENT 

1 n 
n+r 

The logical extent of the font is inclusive between the Y-coordinate values: Y - 
FONT_ASCENT and Y + FONTJDESCENT + 1. 

FONTJDESCENT can be approximated if not provided as a font property, according to the 
following algorithm: 

if (FONTJDESCENT undefined) then 
FONTJDESCENT = maxjoounds.descent 

5.2.3. DEFAULT_CHAR : CARD32 

DEFAULT_CHAR is an unsigned integer value that gives the default character to be used by 
the X server when an attempt is made to display an undefined or non-existent character in the 
font. 

The DEFAULT_CHAR is a 16-bit character (not a two byte character). For a font using two 
byte matrix format, the DEFAULT_CHAR has bytel in the most significant byte and byte2 in 
the least significant byte. If the DEFAULT_CHAR itself is undefined or specifies an 
undefined or non-existent character in the font, then no display is performed. 
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DEFAULT_CHAR can not be approximated if not provided as a font property. 
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Because the X Window System and the Macintosh use different character sets, MacX must 
translate any characters transmitted from one environment to the other. A conversion 
matrix, provided in this appendix, indicates the hexadecimal values for the Apple 
extended ASCII characters used in the Macintosh environment and the ISO Latin 1 
characters used in the X environment. Another pair of charts show the equivalent ISO 
Latin 1 character for each Macintosh extended ASCII character and vice versa. This 
appendix furnishes the matrix and conversion charts as programming aids. 



The matrix in Figure E-l contains complete character sets for Macintosh extended ASCII 
and ISO Latin 1. Macintosh extended ASCII characters are at the top of each cell in teal 
and ISO Latin 1 characters are at the bottom in black. 

To find the character associated with a hexadecimal number, use the column to find 
the high-order digit and the row to find the low-order digit. For example, BO corresponds 
to an infinity symbol W in extended ASCII and a degree sign (°) in ISO Latin 1. 

♦ Italic characters Characters in italic cannot be printed or displayed. They represent 
control characters. ♦ 

Certain characters in each character set have no equivalent in the other character set. 
To see what character is substituted in each case, refer to Figures E-2 and E-3. 
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Figure E-l Character-conversion matrix 
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Figure E-2 shows the equivalent ISO Latin 1 character for a Macintosh extended ASCII 
character. Use the column to find the high-order digit and the row to find the low-order 
digit of an extended ASCII hexadecimal value. The cell at the intersection of these points 
contains the corresponding ISO Latin 1 character. For example, an A8 (®) in extended 
ASCII is converted to a ® (AE) in ISO Latin 1. Each cell in the chart also contains the 
hexadecimal value for each ISO Latin character. 

Legend 

Characters in italic cannot be printed or displayed. They represent control characters. 

Middle dots displayed in teal indicate Macintosh extended ASCII characters for which 
there is no equivalent character in ISO Latin 1. MacX displays or prints these symbols in 
black. When you attempt to type an untranslatable character, your Macintosh beeps. 
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Figure E-2 Macintosh extended ASCII to ISO Latin 1 character mapping chart 
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Figure E-3 shows the equivalent Macintosh extended ASCII character for an ISO Latin 1 
character. Use the column to find the high-order digit and the row to find the low-order 
digit of an ISO Latin 1 hexadecimal value. The cell at the intersection of these points 
contains the corresponding Macintosh extended ASCII character. For example, an AE (®) 
in ISO Latin 1 is converted to a ® (A8) in extended ASCII. Each cell in the chart also 
contains the hexadecimal value for each Macintosh extended ASCII character. 

Legend 

Characters in italic cannot be printed or displayed. They represent control characters. 

Apple symbols (#) displayed in teal indicate ISO Latin 1 characters for which there 
is no equivalent character in Macintosh extended ASCII. MacX displays or prints these 
symbols in black. When you attempt to type an untranslatable character, your 
Macintosh beeps. 
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address mask A code used to identify three classes of 
TCP/IP networks. See also TCP/IP. 

adornment The frame of a window, including, but not 
limited to, the title bar, size and zoom boxes, and 
borders. The window manager controls the adornment of 
windows in X. 

ADSP See AppleTalk Data Stream Protocol. 

ADSP driver A system file that provides ADSP on your 
Macintosh. See AppleTalk Data Stream Protocol. 

alert box A box that appears on the screen to give a 
warning or to report an error message. The warning is 
accompanied by an alert sound. 

alias A substitute name for something. Usually an alias 
is shorter and easier to remember than the original name, 
but it doesn't have to be. 

AppleTalk Data Stream Protocol (ADSP) A 

connection-oriented communications protocol that 
provides a reliable, full-duplex, byte-stream service for 
AppleTalk networks. ADSP ensures in-sequence, 
duplicate-free delivery of data over its connections. See 
AppleTalk network system, communications 
protocol. 

AppleTalk-DECnet Connection Tool A connection 
tool that allows your Macintosh computer to 
communicate with VAX computers through the 



AppleTalk/DECnet Transport Gateway. See also 
AppleTalk/DECnet Transport Gateway, connection 
tools. 

AppleTalk/DECnet Transport Gateway A device that 
translates between AppleTalk and DECnet 
communications protocols on a network. Depending on 
the complexity of the network to which your Macintosh 
is connected, you may have access to more than one 
gateway. See also AppleTalk network system, 
DECnet, gateway. 

AppleTalk network system A networking 
environment that includes computers and other devices, 
software applications, and AppleTalk protocols that 
govern the interactions between the components. The 
specification for the AppleTalk network system was 
created by Apple Computer, and Macintosh computers 
and LaserWriter printers have AppleTalk capabilities built 
in. Other Apple and non-Apple devices may also be able 
to use AppleTalk. For example, AppleTalk for VMS 
allows services and devices on VAX computers running 
the VMS operating system to communicate by means of 
AppleTalk protocols. See also AppleTalk Phase 1, 
AppleTalk Phase 2, AppleTalk protocols. 

AppleTalk Phase 1 Components of the AppleTalk 
network system that predate the development of 
AppleTalk Phase 2. A network may run both AppleTalk 



Phase 1 and AppleTalk Phase 2 at the same time. On 
such a network, a computer that has AppleTalk Phase 1 
installed will be able to see only those network devices 
that use Phase 1— not those that use Phase 2. See also 
AppleTalk network system, AppleTalk Phase 2. 

AppleTalk Phase 2 A new version of AppleTalk 
software that provides extensions to the AppleTalk 
network system, allowing it to support larger and more 
flexible networks. If your network uses both AppleTalk 
Phase 1 and AppleTalk Phase 2, and you have AppleTalk 
Phase 2 installed on your Macintosh, you will be able to 
see other network devices that use AppleTalk Phase 2 as 
well as those that use Phase 1. See also AppleTalk 
network system, AppleTalk Phase 1. 

AppleTalk protocols The set of communication rules 
used in the AppleTalk network system. See also 
communications protocol. 

BDF See Bitmap Distribution Format. 

bitmap A grid of pixels (picture elements) that can be 
set to white or black to create an image. 

Bitmap Distribution Format A source file that, when 
compiled, produces a font in a format usable by MacX. 
Since conventional X servers do not have this built-in 
capability, the BDFtoSNF program is normally used to 
compile BDF font files. The format was developed by 
Adobe Systems, Inc., and accepted as a standard by the X 
Consortium. 

client (1) On a network, a combination of a computer 
and software that lets you access services offered by a 
server, such as printing (print server), access to shared 
files (file server), and so on. The computer that you use 
to access the services — usually your workstation — is 
sometimes referred to as the client, but there is always a 
client software component. In most cases, the client 
software is located on your workstation and the server 
resides on a remote computer. (2) In an X environment, 
an application that runs, in most cases, on a remote host 
computer, although it may run on your workstation. You 
access the client by means of an X server located on your 
workstation. Thus the server-client orientation is reversed 



from the usual arrangement. A client can request the X 
server to display graphics and text and to change or 
report on the X server's state. See also DECwindows 
application, server, X Window System. 

close box The small white box on the left side of the 
title bar of an active Macintosh-style window. Clicking it 
closes the window. 

Color Namer A dialog box that MacX displays to let 
you specify colors. 

colormap A set of color cells that define color values. 
Each cell contains three values specifiying intensities of 
red, green, and blue. MacX uses the colormap to translate 
pixel values into the corresponding RGB values displayed 
on the screen. 

colormap focus The client window whose colormap is 
currently installed and is being used to map pixel values 
to actual displayed colors. 

communications protocol A set of rules that 
determine how information is transmitted and received 
by communicating devices. The communications 
protocols built into networking software perform tasks 
such as acquiring commands from the application that 
you are using, making sure devices are responding 
properly, controlling the connection to the network, and 
moving data between devices. See also AppleTalk 
protocols and DECnet. 

Communications Toolbox See Macintosh 
Communications Toolbox. 

communications tools Pieces of software that supply 
the communications functions that your Macintosh needs 
to communicate with another computer. 
Communications tools fall into three categories: 
connection tools, file-transfer tools, and terminal 
emulation tools. Each type of tool manages a different 
aspect of the communication process. See also 
connection tools, file-transfer tools, terminal 
emulation tools. 

connection tools One of the three types of 
communications tools. A connection tool determines the 
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type of connection that is established between your 
Macintosh and the VAX computer or Digital network. 
Examples: Apple Modem Tool, LAT Tool, Serial Tool. See 
also communications tools. 

DCL See Digital Command Language. 

DECnet The set of network communications protocols 
most often used on Digital networks. See also 
communications protocol. 

DECterm A DECwindows terminal emulation 
application. DECterm allows your Macintosh to emulate a 
VT320 terminal so that you can log in to the VMS 
operating system from the DECwindows environment 
and issue Digital Command Language commands. In 
PATHWORKS for Macintosh, you use MacX to access 
DECterm. See also DECwindows application, Digital 
Command Language, MacX. 

DECwindows A version of the X Window System 
created by Digital Equipment Corporation. DECwindows 
runs under both the VMS and the ULTRIX operating 
systems. You use the MacX server on your Macintosh 
computer to access DECwindows applications running 
on VAX computers. See also MacX, X Window System. 

DECwindows application An X client running on the 
VMS or ULTRIX operating system under DECwindows — 
Digital's implementation of the X Window System. In 
PATHWORKS for Macintosh, you access DECwindows 
applications by using the MacX server on your Macintosh 
computer. See also MacX, ULTRLX, X Windows client, 
X Window System. 

DECwindows client See DECwindows application. 

dialog box A box that contains a message requesting 
more information from you. Dialog boxes that contain 
warnings are called alert boxes. 

Digital Command Language (DCL) The standard 
command interface to Digital's VMS operating system. 
When you log in to VMS, you use DCL commands to 
perform operations such as changing your password or 
displaying a directory of files on the VAX. 



display (1) A set of one or more screens connected to a 
workstation that contains an X server, or (2) a set of one 
or more screens or workstations (comprising a screen, 
keyboard, and printing device) connected to a 
minicomputer that contains an X server. Compare 
screen. 

domain A collection of nodes in a TCP/IP network for 
which a particular name server provides services. See 
also TCP/IP. 

Ethernet A high-speed local area network system that 
uses a variety of cables, such as thick- wire, thin-wire, 
broadband, twisted pair, and so on. The Ethernet 
specification was developed by Digital Equipment 
Corporation, Intel Corporation, and Xerox Corporation. 

Ethernet card A printed circuit board or interface card 
that connects a personal computer, such as a Macintosh, 
to Ethernet and serves as the communications controller 
between the computer and other devices in the Ethernet 
environment. A number of Ethernet cards are available 
for Digital, Apple, and other types of computers. Apple 
provides an Ethernet card called the EtherTalk NB Card. 
See also Ethernet, EtherTalk. 

EtherTalk A high-performance AppleTalk connection. 
EtherTalk consists of an Ethernet interface card, 
AppleTalk software, and Ethernet cabling. EtherTalk 
enables you to use Ethernet cabling in an AppleTalk 
environment. See also AppleTalk network system, 
communications protocol, Ethernet. 

EtherTalk NB card An Ethernet card provided by 
Apple Computer, Inc. See also Ethernet, Ethernet card, 
EtherTalk. 

file-transfer tools One of the three types of 
communications software tools. A file-transfer tool 
ensures that files are transferred intact between your 
Macintosh and the VAX computer or Digital network. 
Examples: Text Tool, XMODEM Tool. See also 
communications tools. 
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FileView A DECwindows application that creates a 
graphical representation of the VMS operating system. 
FileView lets you see the files and directories of a VAX 
computer. The DECwindows Session Manager is preset to 
start FileView automatically. See also DECwindows, 
Session Manager. 

gateway A device that translates between two 
communications protocols on a network. A gateway 
allows network services that use different protocols to 
communicate with each other. See also 
AppleTalk/DECnet Transport Gateway. Compare 
router. 

graphics-based application An application whose 
user interface is composed of graphic elements, such as 
windows, menus, and buttons, as opposed to 
alphanumeric characters. Graphics-based applications 
require display devices with controlling hardware and 
software that enable the display of graphic elements. 

hotspot The part of a pointer that represents its exact 
position on the screen. 

iconify To convert a client window to an icon, a small 
symbol on the screen. Iconifying is a convenient way of 
creating more space on your desktop or temporarily 
setting aside a client without having to close it. 

installation The process of adding or changing 
information on a Macintosh computer. For example, the 
Installer application provided with PATHWORKS for 
Macintosh installs communications and application 
software on your Macintosh. The Installer works with 
Installer script documents that define the software to be 
installed. 

intrinsics A collection of software subroutines and data 
that simplify the process of creating widgets. 

IP address: A binary number that identifies a host and a 
TCP/IP network on which the host resides. The IP 
address is used in data packets to specify their 
destination. 

ISO Latin 1 A character set, based on ASCII, that the 
International Standards Organization has adopted. It is 



the standard character set supported by the X protocol, X 
servers, and clients. Characters with values less than 128 
(decimal) are identical to ASCII characters; those greater 
than 128 are completely different from Macintosh 
extended ASCII characters. See conversion charts in 
Appendix E. 

keyboard input focus The client window designated 
to receive input from the keyboard. 

IAN See local area network. 

layout policy A set of rules that specify the allowable 
sizes and positions of windows and icons. 

local area network (LAN) A group of computers and 
shared devices connected to the same transmission 
cables and located within a limited area, usually a single 
building. 

LocalTalk A system of cables, cable extenders, and 
connector boxes that connect computers and network 
devices. LocalTalk is the cabling system most often used 
to connect Macintosh networks. 

log in In the context of PATHWORKS for Macintosh, to 
open a connection to the VMS operating system. You log 
in to VMS with MacTerminal or, from MacX, by using 
DECterm. 

log-in directory A directory created for you by the 

system administrator when your user name and password 
are assigned. It is the first directory that you see when 
you log in to VMS. 

Macintosh Communications Toolbox A set of 

extensions to the Macintosh system software that 
provides Macintosh applications with standard 
communications services and a consistent interface for 
using those services. For example, MacTerminal uses the 
Communications Toolbox to let you connect to terminal 
services. 

Macintosh extended ASCII An extended version of 
the American Standard Code for Information Interchange 
that contains codes for extra characters used by the 
Macintosh. 
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MacTCP Apple Computer's implementation of the 
TCP/IP family of communications protocols for the 
Macintosh Operating System. See also TCP/IP. 

MacX An application supplied with PATHWORKS for 
Macintosh. MacX is Apple Computer's implementation for 
the Macintosh of the X Window System, providing an X 
server that takes advantage of the Macintosh user 
interface. MacX allows you to access DECwindows 
applications running on VAX computers. See also 
DECwindows application, X Window server, X 
Window System. 

MultiFinder A multitasking operating system for 
Macintosh computers that enables several applications to 
be open at the same time. In addition, processes, like 
print spooling, can operate in the background so that you 
can perform one task while the computer performs 
another. 

network A collection of interconnected, individually 
controlled computers, the hardware and software used to 
connect them, and the communications protocols that 
govern the exchange of information between the 
computers and other devices. A network allows users to 
share data and peripheral devices such as printers and 
storage media, to exchange electronic mail, and so on. 

Network Services Protocol (NSP) One of the DECnet 
family of communications protocols. The 
AppleTalk/DECnet Transport Gateway translates 
between NSP and ADSP, one of the AppleTalk protocols, 
so that AppleTalk-based applications can communicate 
with DECnet-based services, such as DECwindows 
applications. See also AppleTalk/DECnet Transport 
Gateway, AppleTalk Data Stream Protocol, DECnet, 
DECwindows application. 

NSP See Network Services Protocol. 

operating system Software that controls the basic 
operations of a computer. 

PICT Contraction of the word picture. A data format for 
storing graphics. 



pixmap A three-dimensional array of bits or, in other 
words, a stack of two or more bit maps. Pixmaps contain 
the extra pixel values required to represent gray-scale 
and color objects. 

protocol See communications protocol 

protocol family A collection of related protocols that 
together define, for an entire network system, how 
communications are performed. For example, the 
combination of all AppleTalk protocols (such as ADSP) 
makes up the AppleTalk protocol family. See also 
AppleTalk network system, communications 
protocol. 

RAM An acronym for random-access memory, the 
memory chips that store information temporarily while 
you're working on it. RAM can contain both application 
programs and your own information. Information in RAM 
is discarded when you switch the power off. 

remote computer A computer other than your own 
but in communication with yours through 
communication links. A remote computer can be any 
distance from your computer, from right beside it to 
thousands of miles away. 

root window The parent window for all other 
windows in X. In rooted style, MacX maintains the image 
of the root window and all of its subwindows in an off- 
screen bitmap. 

rooted In MacX, a style of operation in which 
DECwindows application windows are displayed in the 
root window. See also MacX, rootless, root window. 

rootless In MacX, a style of operation in which 
DECwindows application windows are displayed in 
Macintosh-style windows, independent of the root 
window. See also MacX, rooted, root window. 

router A device used to link networks that use the 
same communications protocols — but possibly different 
connection media. For example, a router can link and 
allow data to cross between two AppleTalk networks, 
such as a LocalTalk network and an EtherTalk network. 
In Apple parlance, when networks are joined by a router, 
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the result is an internet. The original component 
networks of an internet can be addressed as separate 
entities. When data is transmitted over the internet, the 
router directs the data to its destination by the most 
efficient route. Compare gateway. 

screen The part of a monitor where information is 
displayed, similar to the screen on a television. In MacX, 
a screen is defined by its video type (color or 
monochrome) and a window style (rooted or rootless). 
Compare display. 

server (1) On a network, a combination of hardware 
and software that provides a particular service such as 
access to shared files (file server), printing (print server), 
and so on. The combination of computer and software 
that you use to access the services is called the client. In 
most cases, the client software is located on your 
workstation and the server resides on a remote computer. 
(2) In an X environment, a software component located 
on your workstation that lets you access ("serve up") 
applications. These applications are known as clients, 
and in most cases they run on a remote computer. See 
also client, MacX, X Window System. 

Session Manager A DECwindows application that lets 
you start other applications, lets you customize the 
DECwindows working environment, and provides status 
information about the interaction between your 
Macintosh computer and other DECwindows 
applications. See also DECwindows application. 

settings document A Macintosh document that 
contains the remote commands, preference settings, 
connection-tool settings, and page-setup information that 
you specified to customize your MacX environment. 

shell A UNIX term for a program that interprets 
commands and arranges for their execution. 

size box: A box at the bottom-right corner of most active 
Macintosh windows that lets you resize the window. 

subnet mask Bit values set in the IP address to 
distinguish host addresses from subnetwork addresses. 



By using a subnet mask, the system administrator can 
divide a network into smaller subnetworks. 

TCP/IP A family of communications protocols that lets 
different makes of computers communicate over a variety 
of different types of networks. See also MacTCP. 

terminal emulation tools One of the three types of 
communications tools. The terminal emulation tool that 
you use determines the type of terminal that your 
Macintosh will emulate during the communications 
session. Examples: VT102 Tool, VT320 Tool. See also 
communications tools. 

toolkit A collection of software subroutines and data 
that implements a set of user interface features (widgets), 
such as menus or command buttons, and that allows 
clients to manipulate these features. See also widgets. 

troubleshoot To locate and correct an error, or the 
cause of a problem or malfunction, in hardware or 
software. 

ULTRIX Digital's proprietary version of UNIX— a full 
32-bit operating system that takes advantage of the VAX 
system architecture. 

VMS An interactive operating system that runs all of 
Digital's VAX computers. While you are logged in to the 
computer, you and the system conduct a dialogue of 
command and response. You use the Digital Command 
Language (DCL) to communicate with VMS. VMS stands 
for Virtual Memory System. 

warping A condition in which a client takes control of 
and moves the mouse cursor. 

widgets Graphic objects, such as menus, buttons, and 
scroll bars, used as building blocks to create larger 
images, such as windows and dialog boxes. 

window An area with distinct boundaries, typically 
rectangular in shape, that displays information on the 
screen. You view clients and documents through a 
window. 

window manager A client that allows you to move, 
resize, and change the appearance of windows on the 
screen. 
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workstation A Macintosh or other computer connected 
to a network. 

X protocol A low-level graphics description language 
that permits communications between clients and the X 
server in your desktop computer. 

X Window client (X client) An application, running 
on a remote computer, that you access through an X 
server. For example, DECwindows applications are X 
clients that run on VAX computers; you access them with 
the MacX server on your Macintosh. See also 
DECwindows application, X Window server, X 
Window System. 

X Window environment A computing environment 
based on the X Window System. When you use MacX to 
access DECwindows applications, you are working in an 
X environment. See also X Window System. 

X Window server (X server) The portion of the X 
Window System that controls the display, mouse, and 
keyboard— relaying mouse and keyboard input to clients 
and performing requests from clients to draw graphics on 
the screen. See also X Window System. 

X Window System A network-based system of 
applications (called clients) and servers. The X Window 
System provides a graphical interface by which you can 
access X clients running on a remote computer from a 
server running on your computer. (A graphical interface 
displays graphical elements, such as windows, menus, 
and buttons, rather than alphanumeric characters.) For 
example, DECwindows is a version of the X Window 
System that is implemented on VAX computers. See also 
DECwindows, MacX, X Window client, X Window 
server. 

Xlib A library of software subroutines used by clients to 
communicate with an X server. Xlib contains functions 
for connecting to a particular display server, creating 
windows, drawing graphics, and so forth. 

zone A conceptual (rather than physical) grouping of 
devices and services on a network or internet that makes 
it easier to locate and access network services. Network 



users, devices, and services residing in the same zone can 
be in separate buildings or even in different cities. The 
system administrator defines zones. To access a device or 
service, the user chooses the zone where the device 
resides. Because network devices and services are 
divided into logically related groups, users can locate a 
desired device or service by searching through relatively 
small lists rather than a single large list. In AppleTalk 
Phase 2, a single network can contain several zones, and 
a single zone can cross several networks. 
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A 

Access Control command 16 

remote menu 48, 58 
action buttons 54 

Add style name element 81, 155, 160 

adornment 19 

alert messages 97-98 

American National Standards Institute 

(ANSI) 2 
animation 127 

making smoother 20 
AppleTalk-DECnet Connection Tool 31 
AppleTalk/DECnet Transport 

Gateway 31 
Applications menu 41 

customizing 30 
arrow keys 26 

mouse and 23-24 
Auto Execute command 103 
A/UX manuals xx 
Average capital width element 162 
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B 

B&W Root Preferences command 74 
backward compatibility 126 
BDF. See Bitmap Distribution Format 
files 



Bitmap Distribution Format files 
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file format 135-145 

fonts and 87 
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Cancel button 54 
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Change Settings button 62 
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ASCII 173-179 

control 174 
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error message 112 
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161 

child window 7 
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C key 26 
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color 74 
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Close command 23 
Close Window command 17, 70 
color 8, 89-93 

adding 91-92 
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removing 92 
colormap focus 66 
colormaps 127 
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Command-C 23 
Command key 25 
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MacX 48 

name 37 
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error messages 102-104 
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Command-X 23 
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error messages 99-101 
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remote command 53-54 
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error message 123 
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error messages 104 

MacX 99, 101 
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Copy command 18 
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font names 84 
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Copyright element 168 
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cursor 126 
cursor font 85 

error messages 99, 107 
Cut command 9, 18 
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D 

DCL. See Digital Command Language 
DECterm terminal emulator 42 
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fonts 78 
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DECwindows applications xiii-xiv 

manuals xviii 
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DECwindows Session Manager 106 
DECwindows Window Manager 43 

starting 73-74 
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default settings 19-20 
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window style 68 
Destination element 168-169 
Digital Command Language (DCL) 47 
Discard option 50-51, 60 
Display field 50 
Display pop-up menu 37, 50 
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Edit command 

remote command 58-59 

remote menu 16, 48 
Edit menu 17-18 
End key 26 

End space element 162 
Enter key 26 
error messages 95-124 
Escape key 26 
Ethernet 33, 120-125 
EtherTalk network 121-122 
Execute at Startup box 52 
Execute button 54 
Exit command 70 
DECwindows 43 
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Face name element 168 

Family name element 81, 154, 159 

Figure width element 162-163 

File menu 22-23 

FileView application 40 

fixed font 85 

error messages 100, 107 
Font ascent element 170 
Font descent element 170 
Font Director 8, 79-88 

adding Macintosh font 82-83 
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Font Directory file 78 

error messages 108-109 
font family 80 
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Macintosh format 82 
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Font Substitution 23 
Forward Delete key 26 
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G 

gateway, selecting 34-35 
GrabPointer protocol 126 
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Growable window 67 

H 

hanging, causes 123 
Hide command 17 
root window 74 
Hints 67-68 
Home key 26 
Host button 53 
hotspot 126 
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Iconify command 17, 69-70 
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intrinsics 6 
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K 

keyboard 

differences 25 

error messages 112 
keyboard input focus 66 
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Kill Client command 17, 70-71 

DECwindows 43 
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layout policy 6 

LocalTalk network 33 

low-memory warning system 115-116 

M 

Macintosh fonts 20 
MacroMaker script 112 
MacTCPTool 53 
MacX 

manuals xx 

quitting 29, 44-45 

starting 28-29 

problems 99-102 
MacX Color Namer. See Color Namer 
MacX Colors file 8 

MacX Font Director. See Font Director 
MacX Fonts folder 8, 78 

error message 108 
MacX Window Manager 8, 12, 131-133 
MacX windows 64 
manuals, information xviii-xx 
Massachusetts Institute of Technology 

(MIT) 2 
Maximum space element 161 
memory error messages 115-120 

font names 110 

MacX 102 

remote commands 103 
Method pop-up menu 53 
Minimum space element l6l 
Miscellaneous Preferences dialog 
box 19-20 

password saving 57 
monitor 65. See also screens 
mouse 

buttons 24 

differences 23-24 

preferences 127 
MultiFinder 9 

memory and 116-118 



N 

networks 2-3 

icons 120-122 

problems 120-125 

selecting 32-33 
New command 

file menu 23 

remote menu 15, 48 
New Font Alias dialog box 83-84 
New Font dialog box 82-83 
N key 26 
Node Name 39 
Normal space element 161 
Notice element 168 
Notify option 38, 51 

errors and 98 



O key 26 

Open command 23 
Output field 50-51 
Output pop-up menu 38, 50-51 
Output window 60-62 

P 

Page Down key 26 
Page Setup command 23 
Page Up key 26 
parent window 7 
password 38 

remote command 52 

saving 19-20, 57 
Paste command 9, 18 

color names 93 

font names 84 

PICT format and 132 
Pause feature, error message 106 
PICT format 132 
Pixel size element 81, 155, 160 
Plain box window 67 
Point size element 81, 155, 160 
Pop Up option 51, 60 



preferences 19-20 

animation 127 

mouse-movement 127 

root window 74-75 
Print Clipboard command 23 
printer driver, error message 113 
printer port 123 

printing error messages 112-113 
Print Screen menu 126 
Project Athena 2 

Q 

Quad width element 162 
Quit command 9, 70 

DECwindows 43 

file menu 29 

R 

Registry element 81 
Relative set width element 166-167 
Relative weight element 167 
Remote command 49 

error message 103 
Remote Command dialog box 15-16 

configuring 30, 36-41 

creating commands 49-54 
Remote menu 15-16, 48 

editing 58-59 

executing 59 
remote window manager 73 
Resolution element 167 
Return key 26 
RGB values 89, 92 
road map xx 

Rooted Screen Setup dialog box 74-75 
rooted windows 10-12 

activating 66 
rootless windows 10-12,64 

activating 66 

printing 126 
root windows 71-75 

hierarchy 6-7 
Rounded corner window 67 
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Save command 9 

file menu 23 
Save Lines field 62 
Save option 51 
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PATHWORKS™ for Macintosh' 
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Update to 

MacX User's Guide 



MacX version 1.1.7 has new features that work with PATHWORKS for Macintosh version 
1.1. This update package describes those features and provides information on the 
following topics: 

■ MacX 1.1.7 

■ AppleTalk-DECnet Connection Tool 

■ MacTCP Connection Tool 

■ DECnet Connection Tool 

Replace your existing update module and accompanying connection tools modules 
with the entire contents of this update package. This sheet can be recycled when you 
have finished. 

For information on how to install MacX and other PATHWORKS for Macintosh com- 
ponents, refer to the Installation part of the Network Services User's Guide. The Network 
Services User's Guide tells you how to install MacX using system software version 6.0 .x 
and version 7.0. 
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If you want to use the MacTCP program, you'll need to install the MacTCP Connection 
Tool and configure the MacTCP driver. For installation instructions, refer to the Installation 
part of the Network Services User's Guide. For information on configuring the MacTCP 
driver, see the MacTCP Connection Tool module included with this update package. The 
MacTCP Administrator's Guide provides complete information on the MacTCP driver; see 
your system administrator if you need help. 

If you want to run MacX with A/UX software version 2.0 or later, use the version of 
MacX that came with that A/UX software package. 
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New features in MacX 1.1.7 

MacX version 1.1.7 has several new features that extend its functionality. With MacX version 
1.1.7, you can perform the following operations: 

■ Copy and paste images on your desktop to the Macintosh® Clipboard. 

■ Compile directories of font files. 

■ Display nonrectangular windows created by client applications. 
This section tells you how to use the new features. 

Copying images to the Macintosh Clipboard 

MacX version 1.1.7 lets you copy images appearing on your computer screen(s) to the 
Macintosh Clipboard. You can copy a window displayed by a client application, copy a 
specific area on your screen, or copy the entire desktop. You can then paste the image 
that you copied into other Macintosh and X applications. 

To copy an image from your screen to the Clipboard while running MacX: 

1 Start MacX by double-clicking its icon. 

2 Start a client application. 

3 Choose Copy Screen to Clipboard from the MacX Window menu, or press 
Command-B. 

The pointer changes from an arrow to a crosshair pointer. 
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Copy an image to the Clipboard, using one of the following techniques. 

■ To copy a screen displayed by a client application, position the pointer in the client 
application's window and click the mouse button. 

The contents of the client application's window are copied to the Macintosh Clipboard. 
When you use this technique to copy a screen, the screen image does not include the 
Macintosh window borders. 

■ To copy an image of the desktop, position the pointer in the menu bar or on the 
desktop and click the mouse button. 

An image of your entire desktop, including the menu bar, windows, and icons, is copied 
to the Macintosh Clipboard. 

■ To copy a specific area on your screen, position the pointer on the desktop, drag to 
create a selection box around the area you want to copy, and then release the 
mouse button. 

An image of the selected area is copied to the Macintosh Clipboard. 



Important Remember that the Macintosh Clipboard holds only one image at a time. If 
you copy one image to the Clipboard and then copy a second image, the second image 
replaces the first. A 



You can paste an image from the Macintosh Clipboard into another Macintosh application 
by using the Paste command. You can also paste an image into another X application, if 
the application you're using supports this feature. 



i 
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Compiling directories of font files 

In MacX 1.1.7, you can translate an entire directory of bitmap distribution format (BDF) 
files to a MacX internal format. By translating the directory, you permit these fonts to be 
used by XI 1 clients. (For more information on BDF files, see the MacX User's Guide.) 

To compile a directory of BDF files: 
Start MacX by double-clicking its icon. 

Choose Fonts from the Edit menu, or press Command-F. 

The MacX Fonts window opens. This window lets you use the Font Director. 



□ MacH Fonts 



^-Bitstream 
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-Normal- 
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^j-Bitstream 


-Charter-Bold- 


-Normal- 
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-75 


-P- 
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^-Bitstream- 
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Shouj: | flu Fonts | [ Neuj Font...^ 

Uiem By: [~ Family | [ B<-muu*<^,, ] 

[ Update Font Directory] 

Click the New Font button. 

A new-font dialog box appears, to let you create a new font. 
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New Entry Type: | Macintosh Font | [[ n * | 



Cancel 



Font Family: | Athens 



Point Size: | 12 | 



12 



□ Bold □ Shadow □ Underline 

□ italic □ Outline □ Monospace 



4 Choose X Font from the New Entry Type pop-up menu, as shown in the 
following figure. 

The lower part of the dialog box changes to display two buttons, giving you the option of 
compiling a single BDF file or compiling a folder of BDF files. 



New Entry Type: | H Font | [[ »K j) 



Cancel 



Compile a BDF File ... ] 



Compile a Folder of BDF Files... 



5 Click the Compile a Folder of BDF Files button. 

An open-file dialog box appears, to let you open the folder where the BDF files are stored. 

In the following figure, the BDF files to be compiled are located in the "Fonts" folder on 
Hard Disk. 



6 
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Please open an illustration or a template: 



Hard Disk 



CD flnims 
CD AppleLink 6.0 
lzi Database 

CD HyperMedia 
□ Publishing 
CD System Folder 
CD Utilities 
CD Word Processing 



Hard Disk 



[ J 
[ Driue ] 



Open 
Cancel 



(3 Locate and open the folder containing the BDF files you want to compile. 

The dialog box shows the names of the font files inside the folder. 



|Q fonts | 



□ charB08.bdf 



D charBIO.bdf 

□ charB12.bdf 
D charB14.bdf 

□ charBIB.bdf 
D charB24.bdf 

□ charBIOS.bdf 
D charBMO.bdf 

□ charBM2.bdf 



IS] 



>Hard Disk 



Driue 



Open 
Cancel 



~J Select one of the font files in the dialog box and click the Open button. 

By selecting one of the font files, you are actually specifying that the entire folder of font 
files be compiled. An alert box appears, displaying the message 

Compiling... Please stand by... while the font is being 
compiled (a few seconds) . 

The alert box disappears after the fonts are compiled. 
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8 Click the OK button in the new-font dialog box. 

The new-font dialog box disappears. The newly compiled fonts appear in their original 
folder without the suffix .bdf. For example, the charBio.bdf font files appear in 
the fonts folder as charBi o. The type of the newly compiled file is "MacX document." 
The following figure shows the new MacX font names in the fonts folder. 



iD 




fonts ^= 












Name 


Size 


Kind 


Last Modified 






□ 


charBOS 


7K 


MacX document 


Thu, Nov 1 , 


1990 


1 :32 AM 




<> 


D 


charBOS .bdf 


21K 


document 


Sun, Dec 31 


, 1989 


1 :58 PM 






□ 


charBIO 


8K 


MacX document 
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1990 
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charBIO.bdf 
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document 
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1 :33 AM 






D 
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Sun, Dec 31 
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22K 


document 


Sun, Dec 31 


, 1989 


1 :57 PM 






D 


charBI12 


8K 


MacX document 


Thu, Nov 1 , 


1990 


10:33 AM 
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9 On the desktop, drag the newly created font files into the MacX Fonts folder on 
your hard disk. 

The MacX Fonts folder is located in the MacX 1.1.7 folder that was created automatically 
when you installed MacX on your hard disk. 
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Click the Update Font Directory button in the MacX Fonts window. 

MacX updates the Font Directory file. The new MacX font files appear in the MacX 
Fonts window. 

You can also quit and restart MacX to update the Font Directory file. 
If you're done compiling fonts, close the MacX Fonts window. 
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Displaying nonrectangular windows 



MacX version 1.1.7 allows client applications to display nonrectangular windows, such as 
the circular window displayed by the oclock client application. 

You can apply the Client Specified option on a per- window basis by using the Set 
Window Style submenu in the MacX Window menu. For example, say that you start the 
oclock client application and then choose Client Specified from the Set Window Style 
submenu, as shown in the following figure. The oclock window changes to the style 
defined by the client application: a round window. If you start more client applications, the 
windows will still appear in the standard rectangular form — regardless of the window styles 
defined within the clients — unless you select Client Specified as the default window style 
in the Preferences window. 

For more information about setting window styles with the Set Windows Style sub- 
menu and the Preferences window, see Chapter 4, "Working With Windows," in the 
MacX User's Guide. 



Window ■^■^■^■I^HHH 


Iconify 








Temporarily Rdorn 




Copy Screen to Clipboard- 


:#:B 


Close Window 


#W 


Circulate Up 


:*U 


Circulate Down 


:*D 


Maximize Height 


36M 



fx] Simple 
§1 Growable 
[x] Rounded Boh 
\x\ Shadowed Boh 
\x} Plain Boh 
✓3 Client Specified 



Hide BOW Root Window 
Show Color Root Window 



MacH B&lil Root 
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MacX 1.1.7 hints 



This section provides hints that help you display client applications on your monitor in 
color or on multiple monitors as quickly and clearly as possible. These procedures are 
also described in the MacX User's Guide. This section also tells you how to display motion- 
sensitive clients. 



Displaying client applications in color 

If you're using MacX version 1.1.7 on a color monitor, you can display client applications 
in color. Depending on how you open a client application, you can specify that its window 
appear in color by using either of the two methods described in this section. 



Using the New Remote Command dialog box 
to display client applications in color 

If you are using the New Remote Command dialog box, shown in the following figure, 
choose "(2) Color Rootless" or "(3) Color Rooted" from the Display pop-up menu. For more 
information about displaying client applications in color, see "Creating New Commands" 
in Chapter 3 of the MacX User's Guide. That guide also contains descriptions of MacX 
rooted and rootless modes. 



New Remote Command 



Remote Command: 



Command Name: 



Display: 



Output: 



(0) BGlil Rootless 

(1) BGlil Rooted 

(2) Color Rootless 

(3) Color Rooted 



Username: 
Password: 



□ Euecute at Startup 



[ Bigots ) 



Cancel 
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Using the DECterm or MacTerminal command line to display 
client applications in color 

You can open a client application in color from the command line displayed by DECterm™, 
the MacTerminal® program, or a compatible terminal emulation program. You specify the 
screen number within the command line. The following example is a command line you 
would enter in a MacTerminal window to display the xclock client application in color 
rootless mode — that is, (2) Color Rootless. To use this command, substitute the name of 
your Macintosh for name, and the transport method (for example, ADSP) for transport. 

set di splay /create/ screen=2/node=W#we/transport=£ra/^0fif 
run sys$system: decw$clock 

♦ Note The name parameter must be enclosed in double quotation marks if you're 
using ADSP. ♦ 

To display the xclock client application in color rooted mode — that is, (3) Color 
Rooted— you would enter the following command line, with these stipulations: 

■ Type the name of your computer in place of name to display the client's window on 
your computer screen. 

■ Type the transport method in place of transport. 

1 1 If your transport method is ADSP, enclose name in straight double quotation 
marks. For example, if your transport method is ADSP, then the Macintosh name 
is "Chooser Name :xii@zone" for system software version 6.0. x, or 
"Sharing Setup Name : xi l @zone" for version 7.0. Similarly, if the 
Chooser or Sharing Setup name is Mill Pond, you would enter "Mill 
Pond:Xll@Zone". 

n If your transport method is DECnet™, the Macintosh name is the DECnet node 
name of the Macintosh. 

n If your transport method is TCP/IP, the Macintosh name is the TCP/IP node name 
of the Macintosh. 

set display /create /screen=3/node=mzme/transport=£ra/2S/X)7t 
run sys$system: decw$clock 
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Optimizing the display of client applications on 
multiple monitors 

MacX allows you to display client applications on multiple monitors connected to your 
computer. You can display a client application on one monitor and drag its window to 
another monitor. A client window can even "straddle" monitor boundaries, appearing on 
more than one monitor at the same time. For example, the Xedit window in the following 
figure straddles two monitors. 




Suppose you have two monitors attached to your Macintosh computer. One monitor 
is set to a depth of 1 bit per pixel and the other monitor is set to a depth of 8 bits per pixel. 
You start MacX and create a remote command for the DECW$CLOCK client application. 
You specify that DECW$CLOCK will appear on the 8-bit color monitor, using either the 
color rooted screen or the color rootless screen. You run the command and DECW$CLOCK 
appears in a window on your 8-bit color monitor. 
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MacX draws DECW$ CLOCK fastest on the 8-bit color monitor because you set 
DECW$CLOCK to appear at 8 bits per pixel, using the XI 1 color display capability of MacX. 
If DECW$CLOCK had been set to display in black and white at 1 bit per pixel, the optimal 
speed would have been achieved on the 1-bit monitor. 

To optimize the speed with which MacX draws windows in a multiple-monitor setup, 
position the window on a screen of the same type (color or monochrome) and depth as 
the XI 1 screen on which MacX is drawing the client window. 

For more information about displaying client applications on multiple monitors, see 
"Using Multiple Screens" in Chapter 1 of the MacX User's Guide. 



Displaying motion-sensitive client applications 

Motion-sensitive client applications are applications designed to follow the movements of 
the pointer on the desktop when the application's window is active. For example, the 
xeyes client application displays a pair of eyes that watch the pointer as you move it on 
the desktop. Motion-sensitive client applications may or may not actually follow the pointer, 
depending on the combination of applications appearing on your desktop and the type 
of screen on which you opened each application. 

A motion-sensitive client responds to movements of the pointer only when the client 
is on the same XI 1 screen as the active XI 1 client window. If you display a motion-sensitive 
client window on one XI 1 screen and make active another client window that is displayed 
on a different XI 1 screen, the motion-sensitive window does not respond to the movements 
of the pointer. 
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Troubleshooting 



This section provides possible solutions for problems that may occur when you are using 
MacX with PATHWORKS™ for Macintosh® version 1.1. 

Client applications appear grainy on color screens. 

If a client application of MacX appears grainy on the screen, the application is probably 
attempting to allocate more than the number of free colormap entries. A colormap is a set 
of colorcells that define color values. Each cell contains three values specifying intensities 
of red, green, and blue (RGB). MacX uses the colormap to translate pixel values into the 
corresponding RGB values displayed on the screen. MacX loads standard colormaps for 
the color rooted and color rootless screens. 

These standard colormaps use a certain number of colormap entries, leaving the re- 
maining entries free. Some client applications, such as xgif, attempt to allocate more than 
the number of free colormap entries, and appear grainy on the screen. The client applica- 
tion may display an error message. 

Client applications will have this problem if they make use of all (or nearly all) the 
colormap entries in a standard default colormap. If you are an advanced X user or X 
programmer, you can modify client applications so that each one creates and sets the 
contents of its own colormap. 

Low-memory warnings appear. 

When performing some operations in MacX, your computer may run low on memory. The 
low-memory warning— a flashing "caution" symbol— may appear in your menu bar. You 
can correct this problem by increasing the application memory size of MacX. To increase 
the application memory size or to free memory used by the application, you use the Get 
Info window, as described in Chapter 6, "Troubleshooting," in the MacX User's Guide. It 
is difficult to predict the memory requirements of some operations, so don't allow memory 
space to become critically low. 
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If MacX runs out of application memory, an alert box appears. You should save in a 
MacX settings document any modifications you have made and restart your computer as 
soon as possible to avoid a possible system crash or corruption of data. 

Client applications can't connect to MacX. 

If your DECwindows™ client application cannot connect to MacX, check the Communica- 
tions Folder (system software version 6.0.x) or Extensions folder (version 7.0) in your 
System Folder. Make sure you have only one connection tool for each network protocol 
(TCP/IP, ADSP, and so on). If you have more than one connection tool for a particular 
network protocol, remove one of the tools from the Communications Folder or Extensions 
folder and restart MacX. 

Blank spaces appear in sample text in the MacX fonts window. 

Don't worry if blank spaces (or missing characters) appear in the MacX Fonts window when 
you display a sample of a font. 

For example, if you select Geneva in the MacX Fonts window, the phrase The quick 
brown fox jumps over the lazy dog is usually displayed in the Geneva font. In some cases, 
however, blank spaces may appear instead of characters. The Font Director attempts to 
create a sample of the font you select, whether or not a character used in the sample 
actually exists in the selected font. For example, if you select the Cursor font, the Font 
Director attempts to display the phrase The quick brown fox jumps over the lazy dog in 
that font. If the character fdoes not exist in the Cursor font, a blank space appears in 
its place. 
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MacX keyboard mapping 



Some DECwindows applications have features, such as keyboard equivalents for menu 
commands, that require keys not available on Macintosh keyboards. To permit MacX to 
work properly with such DECwindows applications, you must use a special DECwindows 
application that maps (translates) keys or combinations of keys on your Macintosh key- 
board to keys available on a Digital LK201 keyboard. The application that provides this 
keyboard mapping for MacX is called MSAX$MODMAP. This section tells you how to use 
the MSAX$MODMAP application. 

MSAX$MODMAP modifies and displays mapping tables used by the XI 1 server to trans- 
late keystrokes to key symbols. A mapping table tells the X Window System— in this case, 
MacX— how to translate the keystrokes. The term keysymbol(or keysym) refers to the 
individual location of a key as defined by the software. MacX captures the signals gener- 
ated by the keys specified in the mapping table and translates them to key symbols that 
can be recognized by XI 1 client applications. For example, suppose that the DECwindows 
application you are using requires that you press the Find key on a Digital keyboard. 
Macintosh keyboards do not have a Find key. MSAX$MODMAP solves the problem (in 
one of its several mapping schemes) by mapping the Macintosh Help key to the Find key 
symbol. When you press Help on your Macintosh keyboard, the application you are using 
responds as if you had pressed the Find key on a Digital keyboard. 

The MacX Keyboard Mapping Quick Reference Card, which comes with the MacX User's 
Guide binder, presents the four different keyboard mapping schemes provided by 
MSAX$MODMAP: 

■ positional mapping for Apple (ADB) Extended Keyboard 

■ inscriptional mapping for Apple (ADB) Extended Keyboard 

■ Apple Standard (ADB) keyboard mapping 

■ Macintosh Plus Standard keyboard mapping 
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You can choose the mapping scheme for the kind of keyboard that you are using with 
your Macintosh computer. Use the scheme that best matches the way in which you use 
keyboards and remember the location of keys on a keyboard. 

The positional and inscriptional mappings both work best with the Apple (ADB) 
Extended Keyboard. The positional mapping was designed for people who tend to re- 
member the location of keys by their physical position on the keyboard. Therefore, the 
positional mapping reassigns the meaning of keys on the Extended Keyboard to match 
as closely as possible the location of the Digital keys that the remapped keys are to rep- 
resent. For example, the Help key is mapped to the Find key, because the Find key on a 
Digital keyboard is located in approximately the same position as the Help key on the 
Apple (ADB) Extended Keyboard. 

The inscriptional mapping was designed for people who tend to find keys by their 
names. Therefore, the inscriptional mapping reassigns keys on the Extended Keyboard 
according to their names. For example, the Page Up key on the Extended Keyboard is 
mapped to the Digital keyboard Prev Screen key, because their names have similar 
meanings. 

Of course, for both of these mapping schemes, not every key can be mapped to a 
similar location or meaning. The MacX Keyboard Mapping Quick Reference Card provides 
two ways for you to find the mapped keys: a drawing of the Macintosh keyboard showing 
the mapped keys in teal-colored text, and a table listing the Digital LK201 keys and the 
corresponding Macintosh keys (or key combinations) to which they are mapped. 

The Apple Standard (ADB) Keyboard and Macintosh Plus keyboard mapping schemes 
are provided for users who do not have the Extended Keyboard. Because the Apple 
Standard and Macintosh Plus keyboards have fewer keys than the Extended Keyboard, 
these mapping schemes rely heavily on Command-key combinations. 
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Using the MSAX$MODMAP application 

The MSAX$MODMAP application allows you to issue commands from a remote command 
dialog box or from a terminal emulator such as DECterm. You can also create custom items 
for the Applications menu in the DECwindows Session Manager and FileView™ applica- 
tions, which will run MSAX$MODMAP. You invoke the MSAX$MODMAP application by- 
using Digital Command Language (DCL) commands. If you want to automatically remap 
your keyboard whenever you start the DECwindows Session Manager, you can put the 
commands in a session startup script. (For more information on using a session startup 
script, see the DECwindows User's Guide, published by Digital Equipment Corporation. 
For more information on using DCL commands, see the VMS™ General User's Manual, 
also published by Digital Equipment Corporation.) 

In the example that follows, two DCL command lines are given. The first command 
identifies your Macintosh computer on the network and defines the type of connection 
you are using. (The first command line is needed only when you use MSAX$MODMAP 
from a terminal emulator, such as MacTerminal, before you connect to the DECwindows 
environment with MacX.) The second command line executes MSAX$MODMAP and 
specifies which of the keyboard mapping schemes to use. (You need only the second 
command line, and not the first, if you want to use MSAX$MODMAP as a remote 
command.) 

$ SET D I SPLAY/ CREATE /NODE=wame/TRANSPORT=^raW5p0ft 
$ MCR MSAX$MODMAP MS A$ EXAMPLES : Mapping 

In the sample command lines, the words in italics represent parameters that you should 
replace with appropriate values, as described in Table 1. 

♦ Note The name parameter must be enclosed in straight double quotation marks if 
you're using ADSP. ♦ 



MacX keyboard mapping 19 



Table 1 MSAX$MODMAP command parameters 



ral olltClCl IU 




replace 


Value to enter 


name 


If you're using ADSP, enter your user name as it appears in the Chooser dialog box 




(version 6.0.x) or Macintosh Name in Sharing Setup (version 7.0). If you are communi- 




cating over DECnet, enter your Macintosh computer's DECnet node name. If you're 




using TCP/IP, enter your Macintosh computer's TCP/IP node name. 


transport 


The type of transport you are using: 




ADSP 




DECNET 




TCP IP 


mapping 


One of the following names for the files that provide the specific mapping scheme*: 




MSAX$POSITIONAL EXTENDED KEYBOARD . DAT 




MSAX$INSCRIPTIONAL_EXTENDED KEYBOARD . DAT 




MSAX$ STANDARD KEYBOARD . DAT 



* The MSAX$POSITIONAL JDfTENDEDJCEYBOARD.DAT file provides the positional mapping 
scheme for the Apple (ADB) Extended Keyboard. The 

MSAX$INSCRIPTIONAL JEXTENDEDJKTYBOARD.DAT file provides the inscriptional mapping 
scheme for the Apple (ADB) Extended Keyboard. The MSAX$ STANDARD_KEYBOARD.DAT file 
provides the mapping schemes for both the Apple Standard (ADB) Keyboard and the Macintosh 
Plus keyboard. 



Limitations of MacX version 1.1.7 

This section provides information about the following limitations of MacX version 1.1.7: 

■ dimmed connection tools in the Connection Settings dialog box 

■ conflicts between the XI 1 protocol and Macintosh keyboard characters 

■ macro software incompatibility 

■ conflicts between xclipboard and the Macintosh Clipboard 

■ limits to color-table animation 
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Dimmed connection tools in the Connection Settings 
dialog box 

To create a remote command, you choose a connection tool from the Method pop-up 
menu in the Connection Settings dialog box. Some connection tools that may be listed in 
the Method pop-up menu, do not fully support the remote command facility in MacX. 
Connection tools whose names are dimmed in the Method pop-up menu, such as Apple 
Modem Tool, CTERM Tool, and Serial ISDN Tool in the following figure, cannot be used 
with MacX. 



Connection St 



Method: 



HE 

| %t>t 



RppleTalk RDSP Tool 
RppleTalk-DECnet Tool 
RppleTalk-LfiT Tool 

DECnet Tool 

mBMM 




Host Name or Address : 



Cancel 




MacTCP 

Connection Tool 

for use with MacX only 

1.1.7 © 1988-1991 Apple 
Computer, Inc. 
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Conflicts between the XI 1 protocol and Macintosh 
keyboard characters 

In order to conform to the XI 1 protocol, MacX translates keypresses into a predefined 
set of XI 1 "keysyms." The term keysym refers to the location of a key as defined by the 
software. The XI 1 keysym set contains the XI 1 character set (ISO Latin- 1) and a number 
of special-purpose keys, such as the Return key. If you type a character on a Macintosh 
keyboard that MacX cannot translate into the XI 1 keysym set, MacX causes your Macintosh 
to beep to inform you that the character is unavailable in the MacX environment and has 
been ignored. 

Macro software incompatibility 

Keyboard macro programs that simulate keypresses but do not simulate key-releases, such 
as the MacroMaker™ program, should not be used to simulate keypresses in MacX. 
When MacX receives a keypress simulation and does not receive a subsequent key- 
release simulation, MacX acts as if the key is being pressed continuously. 

Conflicts between xclipboard and the 
Macintosh Clipboard 

MacX uses the built-in Macintosh Clipboard when you cut and paste text. If you run the 
xclipboard client application with MacX, the client application conflicts with the Clipboard. 
To prevent this problem, do not run xclipboard with MacX. 

Limits to color-table animation 

In MacX version 1.1.7, color-table animation works only on color monitors that display 8 
bits per pixel and that are based on a color look-up table (CLUT). 
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DECwindows Motif 



DECwindows Motif is Digital's implementation of the X Window System. This section tells 
you how to access DECwindows Motif with PATHWORKS for Macintosh. DECwindows 
Motif has the minimum memory requirements listed in Table 2. 



Table 2 System requirements for DECwindows Motif 



Monitor 


Computer 


CPU memory 


MacX application 
memory 


Monochrome 


Macintosh Plus 


2 or more megabytes 


1.5 or more megabytes 




or later model 






Color 


Macintosh II family 


4 or more megabytes 


2.5 or more megabytes 




or later model 







You can use DECwindows Motif with MacX as you would use it with any other X 
product. You can access DECwindows Motif with MacX in either of two ways: 

■ You can use a remote command to access the Session Manager, which lets you directly 
execute DECwindows clients such as FileView and Mail. 

■ You can enter your own remote command to access DECterm, and from there start 
other DECwindows applications, such as DECwindows Mail. 

DECwindows Motif assumes that you are using a Digital three-button mouse. You can 
use the arrow keys on your Macintosh keyboard as equivalents for two of the buttons on 
a three-button mouse. For details on how the arrow keys translate to the mouse buttons, 
see Chapter 1 in the MacX User's Guide. 
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Starting the DECwindows Motif Session Manager 

This section tells you how to start the DECwindows Motif Session Manager. When you 
start DECwindows Motif, you are given the option of running a tutorial to help you learn 
about the program. 

To start the Session Manager: 

1 Start the MacX application. 

2 Choose New Command from the Remote menu. 

The New Remote Command dialog box appears. 



Neiu Remote Command 



Remote Command: 



Command Name: 
Display: 



1(0) BGiil Rootless 



0utput: f Saue ~| 



Username: 
Passuiord: 



□ EHecute at Startup 



(LHost^J 



[ Cancel 



3 Start the Session Manager. 

Type the following command in the Remote Command field: 

run sys$system: decw$session 

The Session Manager provides a convenient way to enter the DECwindows environment. 
(Refer to Chapter 2 in the MacX User's Guide for details on the Session Manager.) 
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Fill in the rest of the fields in the New Remote Command dialog box. 

Command Name: Enter a name for the command. 

Display: Choose the item that matches the display environment you're using. 

Output: Choose Save from the pop-up menu. 

Username. Enter the user name assigned to you by your system administrator. 
Password: Enter the password for the user name you just entered. 

Click the Host button. 

The Connection Settings dialog box appears. 

Specify the connection tool that you want to use to connect to the VAX™ 
computer. 

Choose a connection tool from the Method pop-up menu in the upper-left corner of the 
dialog box. You can use the MacTCP®, AppleTalk-DECnet, or DECnet Tool. When you 
choose a tool, the lower part of the dialog box changes to display the settings for that tool. 
Step 7 shows how to configure the AppleTalk-DECnet Tool. For information on config- 
uring one of the other tools, see the reference module for that tool. See your system 
administrator if you're not sure which tool to use. 



Connection Settings 

Method: | HppleTalk-DECnet Tool -r | 



Cancel 




Specify an AppleTalk-DECnet Gateway 



Zone 




Building A 1 st Floor 
Building A 2nd Floor 
Building A 3rd Floor 
Building A 4th Floor 
Documentation 
Finance 

Human Resources 
Marketing 
NorthWest Corner 
NorthEast Corner 
SouthEast Corner 
SouthWest Corner 



DECnet on CURLY 
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7 If you are using the AppleTalk-DECnet Tool, perform the following steps. 

a. Click the Gateway icon in the column of icons at the far left-side of the Connection 
Settings dialog box, if it is not already selected. The zone and gateway settings appear. 

b. Click the name of the zone that contains the gateway to which you want to connect. 
The name you selected appears in the Zone box, and a list of gateways appears on the 
right side of the Connection Settings dialog box. 

c. In the gateways list, click the name of the VAX gateway to which you want to connect. 
The gateway you select can be used to start DECwindows client applications either 
on the same node as the gateway or on a remote VAX. The name you select appears 
in the Gateway box. (You can also type the name of the gateway directly into the 
Gateway box.) 

d. Click the Service icon in the column of icons at the far-left side of the Connection 
Settings dialog box. The lower part of the dialog box changes to let you specify the 
node where DECwindows Motif resides. 



Connection Settings 




Method: |~ RppleTalk-DECnet Tool ▼ | ( Cancel ] 









Specify a DECnet Service 
















Gateway 


! Object : MS AX$CLIENT >S.^<:ii = it 

i O^ivi^ei 1 ; 


1 




J 


Node : | Moe | 


Identity 
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e. Type the node name of the VAX that is running DECwindows Motif, then click OK to 
close the Connection Settings dialog box. The New Remote Command dialog box 
reappears on your screen. 

Click the Execute button in the New Remote Command dialog box. 

After a short time an alert box should appear, stating that a new XI 1 client is attempting 
to connect to MacX. 





R new H1 1 client is 
attempting to connect to 
MacK. Do you wish to 
permit the connection? 




J [ Cancel ] 



This message indicates that the VAX is testing its ability to connect to your Macintosh. 
Click the OK button in the alert box. 

Soon the same alert box should appear again, indicating that DECwindows Motif is connect- 
ing to your Macintosh. This message may appear several times. Click the OK button in the 
alert box each time it appears. Eventually, the DECwindows Session Manager appears. 



=Dl^^ ; Session Manager on MOE 




♦ Note You can suppress the alert boxes by deselecting Access Control in the 
Remote Menu. ♦ 
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10 To learn about DECwindows Motif, run the tutorial by choosing Tutorial from 
the Help menu. 



Session Manager on MOE 




j Session Applications Options 








\ On Window 




i On Basics 




iTutoria] 






i On Version 




iOnHelp 



The tutorial window appears. 



id! Training: Getting Started on UMS DEC windows Motif Sgstems MSB 


Getting Started on 
VMS DECwindows Motif Systems 

Press Return to start the course. 
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Starting DECwindows client applications 
with DECterm 

This section tells you how to start DECwindows applications using DECterm. 
To start DECwindows client applications with DECterm: 

Start the MacX application. 

Choose New Command from the Remote menu. 

The New Remote Command dialog box appears. 



New Remote Command 



Remote Command: 



Command Name: 
Display: 



1(0) BGlil Rootless 



0utput: f Saue ~~| 



Username: 
Passuiord: 



□ Execute at Startup 



LHost^) 



[ Cancel ) 



Start a DECwindows client application with DECterm. 

Type the following command in the Remote Command field. 



create/terminal/ detach 



DECwindows Motif 



4 



5 



6 



Fill in the rest of the fields in the New Remote Command dialog box. 

Command Name: Enter a name for the command. 

Display: Choose the item that matches the display environment you're using. 

Output: Choose Save from the pop-up menu. 

Username: Enter the user name assigned to you by your system administrator. 
Password: Enter the password for the user name that you just entered. 

Click the Host button. 

The Connection Settings dialog box appears. 

Specify the connection tool that you want to use to connect to the VAX 
computer. 

Choose a connection tool from the Method pop-up menu in the upper-left corner of the 
dialog box. You can use the MacTCP, AppleTalk-DECnet, or DECnet Tool. When you 
choose a tool, the lower part of the dialog box changes to display the settings for that tool. 
Step 7 shows how to configure the AppleTalk-DECnet Tool. For information on config- 
uring one of the other tools, see the reference module for that tool. See your system 
administrator if you're not sure which tool to use. 



Connection Settings 

Method: | HppleTalk-DECnet Tool ▼ | 



( Cancel) 




Specify an AppleTalk-DECnet Gateway 

Gateway : | DECnet on MOE 




Building A 1 st Floor 
Building A 2nd Floor 
Building A 3rd Floor 
Building A 4th Floor 
Documentation 
Finance 

Human Resources 
Marketing 
NorthWest Corner 
NorthEast Corner 
SouthEast Corner 
SouthWest Corner 



DECnet on CURLY 
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If you are using the AppleTalk-DECnet Tool, perform the following steps. 

a. Click the Gateway icon in the column of icons at the far-left side of the Connection 
Settings dialog box, if it is not already selected. The zone and gateway settings appear. 

b. Click the name of the zone that contains the gateway to which you want to connect. 
The name you selected appears in the Zone box, and a list of gateways appears on the 
right side of the Connection Settings dialog box. 

c. In the gateways list, click the name of the VAX gateway to which you want to connect. 
The gateway you select can be used to start DECwindows client applications either 
on the same node as the gateway or on a remote VAX. The name you select appears 
in the Gateway box. (You can also type the name of the gateway directly into the 
Gateway box.) 

d. Click the Service icon in the column of icons at the far-left side of the Connection 
Settings dialog box. The lower part of the dialog box changes to let you specify the 
node where DECwindows Motif resides. 



Connection Settings 




Method: [~ flppleTalk-DECnet Tool ▼ | [ Cancel ] 









Specify a DECnet Service 










US 






Gateway 


! Object : MS AX$CLIENT 

! i^.Jfc-ii-il-sr 


\ 




1 


Node : | Moe | 


Identity 
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e. Type the node name of the VAX that is running DECwindows Motif, then click OK to 
close the Connection Settings dialog box. The New Remote Command dialog box 
reappears on your screen. 

8 Click the Execute button in the New Remote Command dialog box. 

After a short time an alert box should appear, stating that a new XI 1 client is attempting 
to connect to MacX. 



fi new H1 1 client is 
attempting to connect to 
MacH. Do you wish to 
permit the connection? 



Cancel 



This message indicates that the VAX is testing its ability to connect to your Macintosh. 

9 Click the OK button in the alert box. 

Soon the same alert box should appear again, indicating that DECwindows Motif is connect- 
ing to your Macintosh. This message may appear several times. Click the OK button in the 
alert box each time it appears. Eventually, the DECterm window appears. 



« File Edit Remote Window Mail 



DECterm: © Digital Equipment Corp. 1988, 1990. 



FJe Edit Control Options Pnnt 



♦ Note You can suppress the alert boxes by deselecting Access Control in the 
Remote Menu. ♦ 



PATHWORKS for Macintosh: MacX User Update 



To learn about DECwindows Motif, run the tutorial. 

a. Type the following command at the $ prompt in the DECterm window. 

run sys$system: decw$cbi 

b. Press Return. 

c. Click OK each time the familiar alert box appears, telling you that a new client is 
attempting to connect to MacX. 

The DECwindows Motif tutorial window appears. Follow the instructions in the window 
to begin the tutorial. 



=□= Training: Getting Started on UMS DECwindows Motif Systems =EDl 


Getting Started on 
VMS DECwindows Motif Systems 

Press Return to start the course. 






■a 
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PATHWORKS™ for Macintosh' 
Version 1.1 



Connection Tools Reference 



Preface 



PATHWORKS for Macintosh includes three connection tools that provide the full-duplex, 
reliable byte-stream communications that MacX requires to connect with X clients — in 
particular, with DECwindows applications. This part of the MacX User's Guide contains 
reference modules for these three connection tools: 

■ AppleTalk-DECnet Connection Tool 

■ MacTCP Connection Tool 

■ DECnet Connection Tool 

Each module is an independent unit that provides reference material for its tool. 



About connection tools 

Connection tools, like all communications tools, work in conjunction with the Macintosh 
Communications Toolbox, an extension of the Macintosh system software. The Communi- 
cations Toolbox manages communications tasks for Macintosh applications. If you're using 
system software version 6.0.x, the Communications Toolbox must be installed on your 
Macintosh before you can use the communications tools. The Communications Toolbox 
is built into version 7.0. 



♦ Note There are two other types of communications tools, known as terminal emu- 
lation tools and file-transfer tools. MacX, however, uses only connection tools. The other 
types of tools are described in the MacTerminal User's Guide. ♦ 

The Installation part of the PATHWORKS for Macintosh: Network Services User's Guide 
provides complete installation instructions for the PATHWORKS for Macintosh software, 
including the Communications Toolbox and communications tools. 

The connection tool you choose to use depends primarily on the operating system 
running on the VAX computer to which you are connecting. There are two operating 
systems commonly used on VAX computers: VMS and ULTRIX. The PATHWORKS for 
Macintosh software is designed to run under the VMS operating system, and therefore the 
MacX User's Guide is oriented toward using MacX to access X clients running under VMS. 
However, MacX can also access X clients running on VAX computers under the ULTRIX 
operating system. ULTRIX is Digital's version of UNIX. 

If you are accessing X clients (DECwindows applications) running under VMS, you will 
need to use either the AppleTalk-DECnet Connection Tool or a DECnet connection tool. 
If you are accessing X clients running under ULTRIX, you will need to use the MacTCP 
Connection Tool or the DECnet Connection Tool. 
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AppleTalk-DECnet 
Connection Tool 



Apple Computer, Inc. 



This manual and the software described in it are copyrighted, with all rights reserved. Under the copyright 
laws, this manual or the software may not be copied, in whole or part, without written consent of Apple, 
except in the normal use of the software or to make a backup copy of the software. The same proprietary 
and copyright notices must be affixed to any permitted copies as were affixed to the original. This 
exception does not allow copies to be made for others, whether or not sold, but all of the material 
purchased (with all backup copies) may be sold, given, or loaned to another person. Under the law, 
copying includes translating into another language or format. 

You may use the software on any computer owned by you, but extra copies cannot be made for this 
purpose. 

The Apple logo is a registered trademark of Apple Computer, Inc. Use of the "keyboard" Apple logo 
(Option-Shift-k) for commercial purposes without the prior written consent of Apple may constitute 
trademark infringement and unfair competition in violation of federal and state laws. 

©Apple Computer, Inc., 1992 
20525 Mariani Avenue 
Cupertino, CA 95014-6299 
(408) 996-1010 

Apple, the Apple logo, AppleTalk, EtherTalk, LaserWriter, LocalTalk, Macintosh, and MultiFinder are 
trademarks of Apple Computer, Inc., registered in the United States and other countries. 

MacX is a trademark of Apple Computer, Inc. 

DECnet, DECwindows, PATHWORKS, and VAX are trademarks of Digital Equipment Corporation. 
ITC Garamond and ITC Zapf Dingbats are registered trademarks of International Typeface Corporation. 
Linotronic is a registered trademark of Linotype Co. 
Microsoft is a registered trademark of Microsoft Corporation. 
Motif is a trademark of the Open System Foundation. 

PostScript is a registered trademark, and Illustrator is a trademark, of Adobe Systems Incorporated. 
Simultaneously published in the United States and Canada. 



The Apple Publishing System 

AppleTalk-DECnet Connection Tool was written, edited, and composed on a desktop publishing system 
using Apple® Macintosh® computers, an AppleTalk® network system, and Microsoft® Word. Proof pages 
were created on the Apple LaserWriter® printers; final pages were printed on a Linotronic® 300. 
PostScript®, the LaserWriter page-description language, was developed by Adobe Systems Incorporated. 

Text type and display type are Apple's corporate font, a condensed version of ITC Garamond®. Bullets are 
ITC Zapf Dingbats®. 
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The AppleTalk®-DECnet™ Connection Tool allows you to connect the MacX™ application 
to DECwindows™ clients through the AppleTalk/DECnet Transport Gateway. The gateway 
is used only to start the DECwindows application. 

The gateway, which runs on a VAX™ computer, performs translations between certain 
AppleTalk and DECnet communications protocols. AppleTalk and DECnet are the principle 
families of communications protocols used by Apple and Digital networks, respectively. 
Specifically, the gateway translates between the AppleTalk Data Stream Protocol (ADSP) 
and the Network Services Protocol (NSP). ADSP is part of the AppleTalk protocol stack; 
NSP is a DECnet protocol. 

By translating from ADSP to NSP and from NSP to ADSP, the gateway allows AppleTalk- 
based applications to communicate with DECnet-based services (such as DECwindows 
applications) as if the services supported ADSP directly. At the same time, DECnet services 
can communicate with AppleTalk applications as if the latter supported DECnet. 

This reference module explains how to select a gateway the first time that you use the 
AppleTalk-DECnet Connection Tool and how to change your gateway selection should 
you need to do so. This reference module also describes the connection settings for the 
AppleTalk-DECnet Connection Tool. 



AppleTalk-DECnet Connection Tool 



What you need 



The Installation part of the Network Services User's Guide provides installation procedures 
for PATHWORKS™ for Macintosh® and describes all of the components, including those 
related to the AppleTalk-DECnet Connection Tool and ADSP driver. The following list 
summarizes the software components required for the AppleTalk-DECnet Connection Tool 
and indicates where each component must be installed. 

■ Macintosh Communications Toolbox— installed in the System file if you're using system 
software version 6.0.x If you're using version 7.0, the Macintosh Communications 
Toolbox is installed automatically in your Macintosh system. 

■ AppleTalk-DECnet Connection Tool— installed in the Communications Folder (version 
6.0. x) or the Extensions folder (version 7.0). 

■ ADSP driver— installed in the System Folder (version 6.0.x). If you're using version 
7.0, the ADSP driver is installed automatically in your Macintosh system. 

If you are connecting to a VAX computer through an Ethernet card installed in your 
Macintosh, you must also have support for AppleTalk Phase 2. If you are using the Apple 
EtherTalk® NB Card, you must install EtherTalk 2.0 software. If you are using some other 
Ethernet card, you must install the equivalent AppleTalk Phase 2 software. See the docu- 
mentation accompanying your Ethernet card for instructions. 



Selecting a network connection 

If your Macintosh is connected to more than one network, you need to make sure that 
you've selected the network containing the VAX that you want to use. If your Macintosh 
is not connected to more than one network, skip this section and proceed directly to 
"AppleTalk-DECnet Connection Settings." 

If your Macintosh is connected to multiple networks, only one network can be active 
at a time. You use the Network device in the Control Panel (if you have system software 
version 6.0.x) or the Network control panel (if you have version 7.0) to select the active 
network. 
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If you're using version 7.0 

To select a network connection: 

1 Choose Control Panels from the Apple (#) menu. 

The Control Panels window opens. 



Control Panels 



9.3 MB in disk 



9.3 MB available 



MacTCP Color 
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Startup Disk Views Easy Access Sharing Setup 



EE 



2 Double-click the Network icon. 

The Network control panel opens. 



Network 



Select an AppleTalk connection : 



LocalTalk 
Built-in 



6 AppleTalk-DECnet Connection Tool 



Select the icon for the network that you want to use. 

The Network Control Panel displays an icon representing each network to which your 
Macintosh is connected. If your computer is attached to a LocalTalk® network, that con- 
nection is usually made through the printer port, and its icon is labeled LocalTalk Built-in, 

You may also have connections to Ethernet environments through Ethernet cards (such 
as the Apple EtherTalk NB Card) installed in your Macintosh. Each icon for an Ethernet 
connection is labeled EtherTalk. If you have more than one Ethernet connection, each 
icon's label includes a number in parentheses, indicating the slot in which the Ethernet 
card is installed. 

Close the Network control panel. 
Close the Control Panels window. 
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If you're using version 6.0.x 

To select a network connection: 



1 Choose Control Panel from the Apple (#) menu. 

The Control Panel window opens. 



Control Panel 



<1# 



Sound 



o 




Desktop Pattern 



Menu Blinking 



o ®oo 

Off 1 2 3 



Rate of Insertion 
Point Blinking 



o ® o 

Slow Fast 



Time (X) 
1 1:09:56 AM 



<§) 12hr. Q24hr. 



Date 

1/16/92 



RAM Cache [32K I (?) ® ° n 
* O0ff 



2 Select the Network icon from the group of icons on the left side of the Control 
Panel window. 



You may have to scroll through the list to find the Network icon. 
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■□I 



Control Panel 



Mouse 



Built-in EtherTalk (2) WHiflllfcM 



O 



Select the icon for the network that you want to use. 

The Control Panel displays an icon representing each network to which your Macintosh 
is connected. If you are attached to a LocalTalk network, that connection is usually made 
through the printer port, and its icon is labeled Built-in. 

You may also have connections to Ethernet environments through Ethernet cards (such 
as the Apple EtherTalk NB Card) installed in your Macintosh. Each icon for an Ethernet 
connection is labeled EtherTalk. If you have more than one Ethernet connection, each 
icon's label includes a number in parentheses, indicating the slot in which the Ethernet 
card is installed. 

Close the Control Panel window. 
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AppleTalk-DECnet connection settings 



To use the AppleTalk-DECnet Tool, you must select an AppleTalk/DECnet Transport 
Gateway and specify the VAX to which you want to connect. You use the Connection 
Settings dialog box to specify the gateway and VAX. 

To access the Connection Settings dialog box, you click the Host button on the right 
side of the MacX New Remote Command dialog box. See your system administrator for 
the values you need to supply in the New Remote Command dialog box. (For information 
on the New Remote Command dialog box, see Chapter 3 in the MacX User's Guide.) 

To specify a gateway and VAX: 

1 Start MacX and choose New Command from the Remote menu. 

The New Remote Command dialog box appears. 



New Remote Command 



Remote Command: 



Command Name: 
Display: 



1(0) Bf>lil Rootless 



0utput:f Saue 1 



Username: 
Password: 



□ EKecute at Startup 

□ $<we Pinsivm il 



LHost^] 



Cancel 



2 Fill in the New Remote Command dialog box with the settings your system 
administrator gave you. 

The settings include the type of command you use to connect to the VAX, how the data 
is displayed on your screen, your user name, and your password. 
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New Remote Command 



Remote Command: 



run sys$system:decuj$session 



Command Name: SessMgr on Moe 



Display: |1 (01 B&UJ Rootless 



Output: ^ Saue 



Username: 
Password: 



smith 



□ Execute at Startup 



GE3 



Cancel 



3 When you've finished entering the values in the New Remote Command dialog 
box, click the Host button. 

The Connection Settings dialog box appears. 

4 Choose AppleTalk-DECnet Tool from the Method pop-up menu in the upper-left 
corner of the dialog box. 



Connection St 


VtppU> Modern lm>\ 
RppleTalk RDSP Tool 


1 •* J 


I Method: 


•/ RppleTalk-DECnet Tool 


[ Cancel ) 




LRT Tool 




MacTCP Tool 

















5 Select a gateway. 

a. Click the Gateway icon in the column of icons at the far-left side of the Connection 
Settings dialog box, if it is not already selected. The zone and gateway settings appear. 
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b. Click the name of the zone that contains the gateway to which you want to connect. 
The name you selected appears in the Zone box, and a list of gateways appears on the 
right side of the Connection Settings dialog box. 

c. In the gateways list, click the name of the VAX gateway to which you want to connect. 
The gateway you select can be used to start DECwindows client applications either on 
the same node as the gateway or on a remote VAX. The name you select appears in 
the Gateway box. (You can also type the name of the gateway directly into the 
Gateway box.) 



Connection Settings 



Method: | RppleTalk-DECnet Tool ▼ | 



Cancel 




Specify an AppleTalk-DECnet Gateway 

Gateway : 



Applications 




Building A 1 st Floor 
Building A 2nd Floor 
Building A 3rd Floor 
Building A 4th Floor 
Documentation 
Finance 

Human Resources 
Marketing 
NorthWest Corner 
NorthEast Corner 
SouthEast Corner 
SouthWest Corner 



DECnet on CURLY 



6 Click the Service icon in the column of icons at the far-left side of the dialog box. 

The lower part of the Connection Settings dialog box changes to display settings that allow 
you to specify a DECnet service. 
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Specify the VAX that's running the DECnet service you want to access. 

Type the VAX name into the node box. For example, if you want to use DECwindows 
Motif, type the name of the VAX on which DECwindows Motif is running. 



Connection Settings ^^^^^H 
Method: f HppleTalk-DECnet Tool ▼ | [ Cancel 1 



J2= 

Identity 



Specify a DECnet Service 



Gateway 



Object 



MSAX$CLIENT 



( w J?i ! .IIYll>SI" 



: MOE 



Click the OK button. 

The Connections Settings dialog box disappears and you return to the New Remote 
Command dialog box. 
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Troubleshooting hints and alert messages 

If problems arise while you are using the AppleTalk-DECnet Tool to communicate with a 
host on a DECnet network, the system displays one or more of the error messages listed 
in this section. Each message appears in an alert box, similar to the one shown in the 
following figure. 




The remote command "MyMotifl" could not be 
ewecuted uia the tool "RppleTalk-DECnet Tool". 
Creation of the remote command stream failed, 



No such node eKists. 



Problems can occur with the Macintosh Communications Toolbox, the AppleTalk connec- 
tion, the AppleTalk/DECnet Transport Gateway, or the DECnet connection. 

This section lists the alert messages that might appear, and suggests actions you can 
take to solve the problem. If you continue to have problems, you may need to reinstall 
the connection tool or contact your system administrator. 
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Communications Toolbox problems 

If a problem occurs with the Macintosh Communications Toolbox, one of the alert 
messages listed in this section will appear. 

The following alert messages may appear when you try to open a connection: 

A timeout occurred while you were attempting to open a 
connection. Check that the computer you are trying to 
connect to is turned on and ready to accept your connection 
request . 

When you executed a remote command in MacX, the Communications Toolbox sent a 
message to the service that you selected, asking to open a connection. Try executing the 
command again. 

Open the Connection Settings dialog box and make sure that you've correctly entered 
the name of the host computer. If the name is correct, ask your system administrator if 
the host computer that you want to access is still available. 

The open request was rejected. 

Try opening the connection again. 

An open or listen request was received for a connection that 
is already open or listening. 

Use the open connection, or close it and open a new connection. 

The following alert messages may appear while you are using the connection: 

No connection is presently open and the operation requires 
an open connection . 

Open a connection, then try the operation again. 
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A close, read, or write was attempted with no open 
connection . 

Open a connection, then try the operation again. 



Requested operation not supported. 

Make sure that you've established a connection to the correct service, then try the 
operation again. 

Requested operation canceled. 

Try the operation again. If the operation is canceled again, try closing the current connec- 
tion and opening a new connection. 

If you see one of the following alert messages, contact your system administrator: 

Generic (cmGenericError) error. 
Generic (cmFailed) error. 
Unknown error number. 

AppleTalk connection problems 

If a problem occurs with the AppleTalk connection, one of the alert messages listed in 
this section will appear. 

The DECnet Gateway name cannot be found on the network . 

The gateway that you selected cannot be located on the network. Open the Connection 
Settings dialog box and make sure that you have selected the correct zone and that the 
gateway is still available. You may also need to check the physical connection between 
your Macintosh computer and the network. 
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This computer' s name cannot be registered because it is 
already in use by someone else . 

The user name that you entered in the Chooser (version 6.0.x) or the Macintosh name 
that you entered in the Sharing Setup control panel (version 7.0) is being used by someone 
else. Open the Chooser (version 6.0.x), or Sharing Setup control panel (version 7.0), 
change the name, then restart MacX. 

AppleTalk doesn't seem to be working. Check to see if 
AppleTalk is turned on in the Chooser. 

Open the Chooser and make sure that AppleTalk is turned on; then restart MacX. 

The ADSP driver doesn't seem to be installed. Check to see 
if the ADSP file is in your System Folder. 

This message will appear only if you're using system software version 6.0.x 

The ADSP file must be in your System Folder. If it is not, place a copy in your System 
Folder and restart your computer. If the ADSP file is in your System Folder, then it may 
be damaged; replace it with a new copy of the file and restart your Macintosh. 

A Read operation was canceled because the connection closed. 

The connection closed while the AppleTalk-DECnet Tool was attempting the operation. 
Open a new connection and try again. 

A Write operation was canceled because the connection 
closed. 

The connection closed while the AppleTalk-DECnet Tool was attempting the operation. 
Open a new connection and try again. 
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There is not enough memory available. 

Close any open connections or documents and try the operation again. If you are using 
MultiFinder®, you may need to quit the application and increase the application memory 
size by using the Get Info dialog box in the Finder. 

Unable to establish a connection with the gateway. 

A problem occurred while the AppleTalk-DECnet Tool was attempting to connect to the 
gateway. Try opening the connection again. 

A connection open operation was canceled while in progress . 

A problem occurred while the AppleTalk-DECnet Tool was attempting to open a connec- 
tion. Try opening the connection again. 

The open connection request was denied by the remote 
machine . 

The VAX computer has denied your request to open a connection. Try opening the 
connection again. If the problem continues, ask your system administrator if the VAX is 
still available. 

The remote machine did not respond to a request to open a 
connection. 

Try opening the connection again. If the problem continues, ask your system administrator 
if the remote computer is still available. 

A serious internal error has occurred. You should quit this 
application . 

Save your work and quit the application immediately. Restart the application, open a 
connection, and try the operation again. 
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The application issued an overlapping I/O call . You should 
quit the application. 

Save your work and quit the application immediately. Restart the application, open a 
connection, and try the operation again. 

An unknown error occurred while trying to register your name 
on the network . 

A problem has occurred with the user name specified in the Chooser (version 6.0.x), or 
the Macintosh name specified in the Sharing Setup control panel (version 7.0). Try 
opening the connection again. If this message reappears, make sure that your user or the 
Macintosh name is entered correctly. 

An unknown error has occurred in the ADSP device driver. 

This message will appear only if you're using system software version 6.0.x 

A problem has occurred with the ADSP file. Try opening the connection again. If this 
message reappears, the ADSP file in your System Folder may be damaged; replace it with 
a new copy of the file. 

An unknown error has occurred in the AppleTalk-DECnet 
Connection Tool . 

Try opening the connection again. If this message reappears, you may need to reinstall 
the connection tool. 
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AppleTalk/DECnet Transport Gateway problems 

If a problem occurs with the AppleTalk/DECnet Transport Gateway, one of the alert 
messages listed in this section will appear. 

Maximum number of sessions with the gateway was reached. 

A system administrator can limit the total number of sessions that a gateway will support. 
If the gateway that you are using supports a limited number of sessions, then you can try 
to establish your connection later. Otherwise, try using another gateway if one is available. 

If you receive one of the following alert messages, contact your system administrator: 

An invalid function was requested of the gateway. 
The gateway is not the same version. 
An invalid length was supplied to the gateway. 
An invalid type was supplied to the gateway. 
Insufficient information was provided. 

DECnet connection problems 

If a problem occurs while the AppleTalk-DECnet Tool is establishing the DECnet portion 
of a connection, one of the alert messages listed in this section will appear. 

No such node exists . 

The DECnet node to which you are trying to connect could not be located. Open the 
Connection Settings dialog box and make sure that you've correctly entered the name of 
the host computer. Also check that you have selected the correct Ethernet card in the 
Control Panel (if you have system software version 6.0..%) or the Network control panel 
(if you have version 7.0), and the correct gateway. If everything is correct, ask your system 
administrator if the host computer that you want to use is still available. 
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No such object exists . 

The service to which you are trying to connect could not be located on the DECnet node. 
Ask your system administrator to make the MSAX$CLIENT service available. 

The remote node could not recognize the log-in information. 

The DECnet node to which you are trying to connect failed to recognize the log-in infor- 
mation that you provided in the Connection Settings dialog box. Open the Connection 
Settings dialog box and make sure that the host name, object description, user name, and 
password are correct. 

User name or password, or both, were found to be invalid. 

The user name, password, or user name and password that you entered in the Connection 
Settings dialog box are not correct. Open the Connection Settings dialog box and make 
sure that you've entered your user name and password correctly; then try opening the 
connection again. If the problem continues, ask your system administrator if you are using 
the correct user name and password. 

The following alert messages may also appear while the AppleTalk-DECnet Tool is trying 
to establish a connection. Try establishing the connection later. If you still have problems, 
contact your system administrator. 

There is not sufficient memory to complete the connection. 

Insufficient system resources on the remote node. 

No I/O channel is available on the gateway node. 

No DECnet logical links are available . 

The DECnet network's object rejected the connection. 

The remote node is no longer accepting connections . 

The remote node is currently unreachable . 
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There was a DECnet network protocol error . 

The DECnet network's logical link was broken. 

The DECnet network is no longer available . 

The DECnet logical link was terminated by a third party. 

The connection to the network object timed out or failed. 

The DECnet network partner task aborted the logical link. 

The DECnet network partner task disconnected the logical 
link. 

The DECnet network partner task exited before confirming the 
logical link. 

The path to the DECnet partner task node was lost . 
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The MacTCP® product is Apple Computer's implementation of the TCP/IP family of 
protocols for the Macintosh® Operating System. Named after the two best-known protocols, 
Transmission Control Protocol and Internet Protocol, this protocol suite was developed 
by the Defense Department's Advance Research Projects Agency (DARPA). Over the years, 
the TCP/IP protocol stack has evolved into an efficient way to connect different makes of 
computers on diverse networks. 

MacTCP is composed of two specialized software modules that enable your Macintosh 
computer to communicate over a TCP/IP network: a driver and a connection tool. The 
driver processes data passing to and from the Macintosh port connected to the TCP/IP 
network. The driver interfaces with the Macintosh Operating System, packaging outgoing 
data for the TCP/IP network and translating incoming data packets into a Macintosh format. 
The connection tool works in conjunction with the Macintosh Communications Toolbox — 
the software that manages communications tasks for Macintosh communications 
applications such as MacX™. 

This reference module describes the connection settings for the MacTCP Connection Tool 
and tells you how to configure the MacTCP driver. You may need to obtain additional 
configuration information from your system administrator. This module also provides 
suggestions for solving connection problems. 

A Important The way that MacTCP is implemented on your network depends on the lay- 
out of the network. This section provides as much information as possible to help you 
use MacTCP, but your system administrator may need to follow a different implementation 
scheme than the one described in this module. A 
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What you need 

You must have the following software components installed to use the MacTCP Tool. For 
installation instructions, see the Installation part of the Network Services User's Guide. 

■ Macintosh Communications Toolbox— installed in the System file if you're using system 
software version 6.0.x If you're using version 7.0, the Macintosh Communications 
Toolbox is installed automatically in your Macintosh system. 

■ MacTCP Connection Tool — installed in the Communications Folder (version 6.0.x) 
or Extensions folder (version 7.0). 

■ MacTCP driver— installed in the System Folder. 

If you are connecting to a VAX™ computer through an Ethernet card installed in your 
Macintosh, you must also have support for AppleTalk® Phase 2. If you are using the Apple 
EtherTalk® NB Card, you must install EtherTalk Phase 2 software. If you are using some 
other Ethernet card, you must install the equivalent AppleTalk Phase 2 software. See the 
documentation accompanying your Ethernet card for instructions. 



Configuring the MacTCP driver 

Before you can use the MacTCP Connection Tool, you must configure the MacTCP driver. 
Ask your system administrator if arrangements have already been made to help you con- 
figure your MacTCP driver. For example, your system administrator may provide this service 
for you, or you may need to get configuration information that resides on your VAX. You 
may not need to use this section if your system administrator plans to configure the MacTCP 
driver in some other way. 

A For system administrators The configuration instructions in this reference module 
address the needs of the network user who simply wants to connect a Macintosh to an 
existing TCP/IP network. If you are a system administrator or are installing a TCP/IP 
network, please consult the MacTCP Administrator's Guide, a 
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Configuring the driver involves performing the following tasks: 

■ opening the control panel to prepare for a link-level connection 

■ selecting your network type and verifying it with the system administrator 

■ specifying settings in the MacTCP administrator dialog box 

Preparing for a link-level connection 

This section tells/you how to open the control panel in order to select a link-level con- 
nection for the pacTCP driver. The link-level connection defines the way you physically 
connect your Macintosh to the TCP/IP network. MacTCP supports three different kinds 
of connections between Macintosh computers and TCP/IP networks: 

■ LocalTalk® 

■ EtherTalk 

■ Ethernet 

Each type of connection is represented by a unique icon in the control panel. (Through- 
out the rest of this module, the term control panel is used to refer to both the MacTCP 
control panel in system software version 7.0 and the Control Panel in system software 
version 6.0.x) The procedure that you follow if you are using system software version 
7.0 is slightly different from the procedure you follow if you are using version 6.0.x 
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If you 're using version 7.0 

To begin selecting a link-level connection: 

1 Choose Control Panels from the Apple (#) menu. 

The Control Panels window opens. 



1 1 


m== Control Panels si 


Ml 


1 8 items 


9.3 MB in disk 


9.3 MB available 



Memory 



9 



General Controls Keyboard 



Map File Sharing Monitor 



Labels Network Users & Groups 



Startup Disk Views 



Easy Access Sharing Setup 



&1 



2 Double-click the MacTCP icon. 

The MacTCP control panel appears. 
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EtherTalk 


Ethernet 














IP Address: 


jO.O.0.0 j 




[More... ] 



If your system administrator requires that you perform the full configuration, you use this 
control panel to set link information for your particular network. 

3 Go on to "Selecting Your Network Type," later in this module, to complete the 
selection of your link-level connection. 
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If you're using version 6.0.x 

To begin selecting a link-level connection: 

Choose Control Panel from the Apple (#) menu. 

The Control Panel window opens. 

Select the MacTCP icon from the column of icons at the far-left side of the window. 

You may have to use the scroll bar to find the icon. 

The upper part of the Control Panel window displays one or more icons labeled LocalTalk, 
EtherTalk, or Ethernet. 
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[ More... ] 




3.3.2 







Go on to the next section, "Selecting Your Network Type," to complete the 
selection of your link-level connection. 
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Selecting your network type 

This section explains what each kind of icon displayed in the control panel means. To 
select the right icon, you need to know the type of router through which your Macintosh 
will transmit data. If you are unsure which icon to select, your system administrator can 
help you select the one that will give you the best network performance. 

LocalTalk 

Selecting the LocalTalk icon connects your Macintosh to a LocalTalk network. LocalTalk 
usually transmits data at lower speeds than an EtherTalk or Ethernet network, so if your 
control panel also contains an EtherTalk or Ethernet icon, you're usually better off 
selecting that icon. Select LocalTalk if it's the only link-level icon displayed. 

If you select LocalTalk, you need to use an AppleTalk-IP gateway to transmit data to 
hosts on a TCP/IP network. This gateway should be located in one of the zones listed in 
the pop-up menu below the LocalTalk icon in your control panel. 

If your network uses an AppleTalk-IP gateway such as Shiva FastPath or Cayman 
GatorBox, click the LocalTalk icon. Otherwise, contact your system administrator for 
alternative connections. 

♦ Note An AppleTalk-IP gateway (also called a DDP-IP gateway) translates the Datagram 
Delivery Protocol (DDP) packets sent by an AppleTalk network into the Internet Protocol 
(IP) packets sent by an Ethernet network so that computers and other devices on these 
two different networks can communicate. ♦ 

If your control panel displays a LocalTalk icon only, you must configure the MacTCP 
driver for a LocalTalk network. The section "If You're Using a LocalTalk Connection," later 
in this module, tells you how to specify settings for this type of network. If you want faster 
network performance, ask your system administrator about having an Ethernet card 
installed in your computer. 
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EtherTalk and Ethernet 

This section can help you select the best network choice if you have the option of using 
either EtherTalk or Ethernet. Determine whether your network uses an AppleTalk-IP 
gateway, such as Shiva FastPath, or if it can directly access an IP host or router. 

■ If your network uses an AppleTalk-IP gateway, click the EtherTalk icon. 

■ If your network can access an IP host or router directly, click the Ethernet icon. 

EtherTalk Selecting the EtherTalk icon connects your Macintosh to an EtherTalk network. 
If you are using system software version 6.0.x, the pop-up menu below the icon lists all 
the zones on your network. One of these zones contains the AppleTalk-IP gateway needed 
to translate the AppleTalk Datagram Delivery Protocol packets transmitted by your 
Macintosh into the Ethernet IP packets recognized by the TCP/IP network. 

If two EtherTalk icons appear in the control panel, you have access to two different 
EtherTalk networks. Each network is identified by a number (in parentheses) that indi- 
cates the slot in your Macintosh that contains the Ethernet card. Select the EtherTalk icon 
representing the network that you want to use. 

Ethernet Selecting the Ethernet icon connects your Macintosh to an Ethernet network. 
Ethernet provides much faster data transmission than EtherTalk. However, before you 
can use an Ethernet connection, you must verify that your Macintosh can transmit Ethernet 
Internet Protocol packets directly through an IP router. Otherwise, your Macintosh is 
probably part of an EtherTalk network, which uses a different packet format and conse- 
quently requires an AppleTalk router. 

If two Ethernet icons appear in the control panel, you have access to two different 
Ethernet networks. Each network is identified by a number (in parentheses) that indicates 
the slot in your Macintosh that contains the Ethernet card. Select the Ethernet icon repre- 
senting the network that you want to use. 
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Specifying settings in the administrator dialog box 

Once you've selected your link-level connection, you're ready to specify settings in the 
MacTCP administrator dialog box. This section tells you how to fill in the dialog box for 
each of the three types of connections. 

If you're using a LocalTalk connection 

This sections pertains to you only if you have selected the LocalTalk icon in the control 
panel, as described in the preceding section. To configure the MacTCP driver for a 
LocalTalk connection, you need to fill in the MacTCP administrator dialog box. 

The MacTCP administrator dialog box appears when you click the More button in the 
control panel. Your system administrator may have configured the MacTCP administrator 
dialog box for you, or may have special instructions for performing the configuration, such 
as directing you to your VAX for the needed information. 

To fill in the MacTCP administrator dialog box for a LocalTalk connection: 

1 Click the More button at the bottom of the control panel. 

The administrator dialog box appears. 

2 Specify each setting. 

You may have to consult with your system administrator to obtain the needed information. 
Brief descriptions of the settings follow. For details on the MacTCP administrator dialog 
box, see your system administrator or refer to the MacTCP Administrator's Guide. 

The information that you enter in the administrator dialog box (Obtain Address, IP Address, 
Routing Information, and Domain Name Server Information) varies depending on the 
network in use. 
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Obtain Address: 



IP Address: 



Manually 
O Seruer 
O Dynamically 



Class: ] fl | Address: 90.25.0.0 
Subnet Mask: 255.255.252.0 
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■Routing Information:-: 
Gateway Rddress: 



Net I Subnet I Node 

Bits: 8 14 10 

Net: 190 ; £x] Lock 

Subnet: neoo ; H Lock 



Node: |o ~| □ Lock 



|90. 10.240. r 



Domain Name Server Information: 

Domain IP Address Default 




| OK j| [ Cancel ] 



l l I O 



Obtain Address: Click the Server button in the Obtain Address area of the administrator 
dialog box. When you select Server, the IP address is assigned for you automatically. 

Class: Use this pop-up menu to select a class. Ask your system administrator if you need 
to set the address class or subnet mask. (Ask for the subnet mask in dotted decimal 



The address is a code used to identify three classes of networks. Each class specifies a 
maximum number of hosts permitted. 

The subnet mask consists of bit values set in the IP address to distinguish host addresses 
from subnetwork addresses. By using a subnet mask, the system administrator can divide 
a network into smaller subnetworks. Drag the slider along the address bar until the correct 
subnet mask number appears above it. 

Routing Information: Enter the gateway address supplied by your system administrator, 
then click OK. The default gateway address identifies individual networks within a group 
of interconnected networks (an internet). 



notation.) 
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Domain Name Server Information: A domain is a collection of nodes for which a particular 
name server provides services. If you can use more than one server, find out the default 
domain name first. An IP address is a binary number that identifies a host and the network 
on which it resides. The IP address is inserted in data packets to specify their destination. 

Ask your system administrator for the default gateway address — in other words, the IP 
address of the IP router on your local network. 

A Hosts file is a text file that lists hosts and domain servers and their TCP/IP addresses. This 
file is especially useful if you don't have access to a domain name server where this infor- 
mation is typically updated for you, and instead you have to update host information 
yourself. If you have the option of using a Hosts file, determine whether you should use 
it. If so, contact your system administrator for help in updating the Hosts file in your System 
Folder with the names of the hosts that you currently use. Unless you get an updated 
Hosts file, the Host List in your remote command's Connection Settings dialog box will 
be blank. 

If your system administrator recommends using a Hosts file, update the one that you 
dragged into your System Folder, or replace it with one that your system administrator 
provides. Either you or your system administrator will have to update your Hosts file as 
you change the hosts that you use. (For information on creating a Hosts file, see your 
system administrator or Appendix A in the MacTCP Administrator's Guide) 

Restart your Macintosh computer. 

Now you're ready to start MacX. See Chapter 2 in the MacX User's Guide for instructions. 
For an overview of the X Window System and MacX, read Chapter 1 as well. 
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If you're using an EtherTalk connection 

This section pertains to you only if you have selected the EtherTalk icon in the control 
panel as described in "Selecting Your Network Type," earlier in this module. To configure 
the MacTCP driver for an EtherTalk connection, you need to fill in the MacTCP adminis- 
trator dialog box. The MacTCP administrator dialog box appears when you click the More 
button in the control panel. Your system administrator may have configured the MacTCP 
administrator dialog box for you, or may have special instructions for performing the 
configuration, such as directing you to your VAX for the needed information. 

To fill in the MacTCP administrator dialog box for an EtherTalk connection: 

Click the More button at the bottom of the control panel. 

The administrator dialog box appears. 

Specify each setting. 

You may have to consult with your system administrator to obtain the needed information. 
Brief descriptions of the settings follow. For details on the MacTCP administrator dialog 
box, see your system administrator or refer to the MacTCP Administrator's Guide. 

The information that you enter in the administrator dialog box (Obtain Address, IP Address, 
Routing Information, and Domain Name Server Information) varies depending on the 
network in use. 
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Obtain Address: 

(•) Manually 

O Seruer 

O Dynamically 



•Routing Information: 
Gateway Address: 



IP Address: 

Class: [ H 1 Address: 90.25.0.0 
Subnet Mask: 255.255.252.0 

I I llll II iilil T I II iL 



Net 
Bits: 8 



Subnet I Node 
14 10 



Net: |90 
Subnet: hsoo 
Node: [o 



IS] Lock 
Lock 
□ Lock 



Cancel 



•Domain Name Server Information: 

Domain IP Rddress Default 



| acct .bonzinicorp .corn"] |l 1 1 .25.15.5 



1 o 



Obtain Address: Click the Manually radio button in the Obtain Address area of the 
administrator dialog box. 

Class: Use this pop-up menu to select a class. Ask your system administrator if you need 
to set the address class or subnet mask. (Ask for the subnet mask in dotted decimal 
notation.) 

The address is a code used to identify three classes of networks. Each class specifies a 
maximum number of hosts permitted. 

The subnet mask consists of bit values set in the IP address to distinguish host addresses 
from subnetwork addresses. By using a subnet mask, the system administrator can divide 
a network into smaller subnetworks. Drag the slider along the address bar until the correct 
subnet mask number appears above it. 

Routing Information: Enter the gateway address supplied by your system administrator, 
then click OK. The default gateway address identifies individual networks within a group 
of interconnected networks (an internet). 
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Domain Name Server Information: A domain is a collection of nodes for which a particular 
name server provides services. If you can use more than one server, find out the default 
domain name first. An IP address is a binary number that identifies a host and the network 
on which it resides. The IP address is inserted in data packets to specify their destination. 

Ask your system administrator for the default gateway address — in other words, the IP 
address of the IP router on your local network. 

A Hosts file is a text file that lists hosts and domain servers and their TCP/IP addresses. 
This file is especially useful if you don't have access to a domain name server where this 
information is typically updated for you, and instead you have to update host information 
yourself. If you have the option of using a Hosts file, determine whether you should use 
it. If so, contact your system administrator for help updating the Hosts file in your System 
Folder with the names of the hosts that you currently use. Unless you get an updated 
Hosts file, the Host List in your remote command's Connection Settings dialog box will 
be blank. 

If your system administrator recommends using a Hosts file, update the one that you 
dragged into your System Folder, or replace it with one that your system administrator 
provides. Either you or your system administrator will have to update your Hosts file as 
you change the hosts that you use. (For information on creating a Hosts file, see your 
system administrator or Appendix A in the MacTCP Administrator's Guide) 

Restart your Macintosh computer. 

Now you're ready to start MacX. See Chapter 2 in the MacX User's Guide Tor instructions. 
For an overview of the X Window System and MacX, read Chapter 1 as well. 
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If you're using an Ethernet connection 

This section pertains to you only if you have selected the Ethernet icon in the control panel 
as described in "Selecting Your Network Type," earlier in this module. To configure the 
MacTCP driver for an Ethernet connection, you need to complete the MacTCP administrator 
dialog box. The MacTCP administrator dialog box appears when you click the More button 
in the control panel. 

Your system administrator may have configured the MacTCP administrator dialog box 
for you, or may have special instructions for performing the configuration, such as directing 
you to your VAX for the needed information. 

To fill in the MacTCP administrator dialog box for an Ethernet connection: 

1 Click the More button at the bottom of the control panel. 

The administrator dialog box appears. 

2 Specify each setting. 

You may have to consult with your system administrator to obtain the needed information. 
Brief descriptions of the settings follow. For details on the MacTCP administrator dialog 
box, see your system administrator or refer to the MacTCP Administrator's Guide. 

The information that you enter in the administrator dialog box (Obtain Address, IP Address, 
Routing Information, and Domain Name Server Information) varies depending on the 
network in use. 
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Obtain Address: 

(•) Manually 

O Seruer 

O Dynamically 



•Routing Information: 
Gateway Address: 

|90. 1Q.240.1 ~| 



IP Address: 

Class: | H 1 Address: 90.25.0.0 
Subnet Mask: 255.255.252.0 
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Net 
Bits: 8 

Net: |90 
Subnet: neoo 
Node: [o 
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Cancel 



•Domain Name Server Information: 

Domain IP Address Default 
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o 
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Obtain Address: Click the Manually radio button in the Obtain Address area of the 
administrator dialog box. 

Class: Use this pop-up menu to select a class. Ask your system administrator if you need 
to set the address class or subnet mask. (Ask for the subnet mask in dotted decimal 
notation.) 

The address is a code used to identify three classes of networks. Each class specifies a 
maximum number of hosts permitted. 

The subnet mask consists of bit values set in the IP address to distinguish host addresses 
from subnetwork addresses. By using a subnet mask, the system administrator can divide 
a network into smaller subnetworks. Drag the slider along the address bar until the correct 
Subnet Mask number appears above it. 

Routing Information: Enter the gateway address supplied by your system administrator, 
then click OK. The default gateway address identifies individual networks within a group 
of interconnected networks (an internet). 
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Domain Name Server Information: A domain is a collection of nodes for which a particular 
name server provides services. If you can use more than one server, find out the default 
domain name first. An IP address is a binary number that identifies a host and the network 
on which it resides. The IP address is inserted in data packets to specify their destination. 

Ask your system administrator for the default gateway address — in other words, the IP 
address of the IP router on your local network. 

A Hosts file is a text file that lists hosts and domain servers and their TCP/IP addresses. 
This file is especially useful if you don't have access to a domain name server where this 
information is typically updated for you, and instead you have to update host information 
yourself. If you have the option of using a Hosts file, determine whether you should use 
it. If so, contact your system administrator for help updating the Hosts file in your System 
Folder with the names of the hosts that you currently use. Unless you get an updated 
Hosts file, the Host List in your remote command's Connection Settings dialog box will 
be blank. 

If your system administrator recommends using a Hosts file, update the one that you 
dragged into your System Folder, or replace it with one that your system administrator 
provides. Either you or your system administrator will have to update your Hosts file as 
you change the hosts that you use. (For information on creating a Hosts file, see your 
system administrator or Appendix A in the MacTCP Administrator's Guide) 

If you need to supply an Ethernet address, go to step 3. If not, go to step 4. 



MacTCP Connection Tool 



If you need to supply an Ethernet address, perform the following steps: 

a. Click the Server radio button in the Obtain Address area. 

b. Click the OK button to return to the control panel. 

c. Close the control panel. 

d. If you're running system software version 7.0, close the Control Panels window. 

If you don't need to supply an Ethernet address, perform the following steps: 

a. Click the OK button to return to the control panel. 

b. Type the IP address for your computer in the IP Address field in the control panel. 

c. Close the control panel. 

d. If you're running system software version 7.0, close the Control Panels window. 
Restart your Macintosh computer. 

Now you're ready to start MacX. See Chapter 2 in the MacX User's Guide for instructions. 
For an overview of the X Window System and MacX, read Chapter 1 as well. 
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MacTCP connection settings 



Once MacTCP is installed and the MacTCP driver is configured, you can establish a con- 
nection with a host computer on a TCP/IP network by selecting the host's name from the 
Host List in the MacTCP Connection Settings dialog box, shown in the following figure. 
In MacX, the dialog box appears when you click the Hosts button in a New Remote 
Command dialog box. (See Chapter 3 in the MacX User's Guide for information on using 
the New Remote Command dialog box.) 



Connection Settings |[ 0K lt~J 

Method: [~ MacTCP Tool ▼! [ Cancel ] 



goofy.apple.com. 
slug.aux.apple.com. 



Host Name or Address : 



goofy.apple.com 




MacTCP 

Connection Tool 

for use with MacX only 

1 .1 .7, © 1988-1991 Apple 
Computer , Inc. 



When the MacTCP Connection Settings dialog box appears on your screen, a list of 
host names should appear in the Host List. Double-click a name to select it. The selected 
name appears in the box labeled "Host Name or Address." You can also type a name or 
IP address directly into this box. 

If you don't see a list of host names in the Host List, your System Folder probably does 
not contain a Hosts file. You can enter a host name or IP address in the "Host Name or 
Address" box, but when you quit your application, the entry is discarded. Using a Hosts 
file makes it unnecessary for you to continuously enter host names. Remember that this 
file must be updated when host addresses change or new hosts are added to the network. 
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Troubleshooting hints 

If problems arise while you are using MacTCP to communicate with a host on a TCP/IP 
network, the system displays one or more of the error messages listed in this section. Each 
message appears in an alert box similar to the one shown in the following figure: 




The remote command ".siug.xterm.2" could not be 
executed uia the tool "MacTCP Tool". Creation of 
the remote command stream failed. 



The connection came up halfway and then failed. 



The MacTCP error string appears at the end of a message and is always preceded by 
an introductory phrase such as this one: 

The MacTCP Tool tool error was: 

Because most MacTCP error messages are short, this section explains the problems that 
might arise and how to recover from them. 

A Important If you receive an error message that is not listed in this section, the error is a 
Macintosh system error. Write down the error message, save any work in progress, restart 
your computer, and report the error to your system administrator. Internal errors are not 
likely to occur unless you are developing or testing an application. A 
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Duplicate IP address or unable to obtain address from 
server . 

Depending on how you set up MacTCP to obtain an IP address, your IP address is either 
incorrect or being used by another computer, or the server cannot provide one. Check 
the administrator dialog box to see how MacTCP obtains an IP address. (For information 
on the administrator dialog box, see "Specifying Settings in the Administrator Dialog Box," 
earlier in this module.) 

■ If the Manually radio button is selected in the MacTCP administrator dialog box, verify 
that the IP address in the control panel is correct. If there is no address, obtain one from 
your system administrator. You should probably repeat the entire configuration pro- 
cedure to be sure that it is correct. (Follow the instructions in "Configuring the MacTCP 
Driver," earlier in this module.) 

■ If the Server radio button is selected in the MacTCP administrator dialog box, contact 
your system administrator. The BootP (Bootstrap Protocol) or RARP (Reverse Address 
Resolution Protocol) server cannot give you an address. 

Error in MacTCP load. 

While MacX was starting up, the MacTCP driver was unable to load itself into memory. This 
problem can occur because MacX doesn't have enough memory allocated to it, the operat- 
ing system is malfunctioning, or MacTCP is corrupted. If, despite this error, MacX started 
up, choose About MacX from the Apple menu to see how much memory is available. If 
less than 100 kilobytes (K) is free, quit MacX, then click the MacX application icon once 
in the Finder™. From the Finder, choose Get Info from the File menu, and increase the 
MacX application memory size in the Get Info dialog box. 

If MacX is not short of memory, try replacing the MacTCP driver in your System Folder 
with a known good driver. If the same error recurs, try reinstalling your system software 
as a last resort. Refer to the chapter on creating a startup disk in the Macintosh User's Guide 
for instructions. Remember to back up your current disk first and to install version system 
software 6.0.5 or a later version. 
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No gateway available to handle routing of packets to off- 
network destinations . 

MacTCP cannot build a connection to the host to which you want to log in. Call your system 
administrator for assistance. 

No name server can be found for the specified name string. 

You have issued a remote command, but no domain name server can be associated with 
the domain name in the host name string. This string is the one you selected in the 
Connection Settings dialog box when you created the remote command. To display the 
Connection Settings dialog box, press and hold down the Option key, choose the remote 
command from the Remote menu, and click the Hosts button in the New Remote Command 
dialog box. Verify that the host name in the "Host Name or Address" box is spelled 
correctly. If it is, call your system administrator for assistance or try using the host's IP 
address instead. 

None of the known domain name servers is responding. 

The domain name servers are not available, either because they are not working or because 
the network is down. Call your system administrator for assistance. 

Not enough memory is available to issue the needed domain 
name resolver query or to build the DNR cache. 

MacTCP does not have enough memory to look up the domain name string required to 
execute your remote command. Your Hosts file may contain too many names, or MacX 
may not have enough memory allocated to it. To find out if the Hosts file has too many 
names, quit MacX and check the size of the file in the Get Info box. You'll find the Hosts 
file in your System Folder. Click it and choose Get Info from the File menu. If the applica- 
tion memory size is greater than 2,000 kilobytes (K), the file is probably too large. Open 
the Hosts file and delete any host names you don't use. 
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If the Hosts file is not too large, start MacX again and choose About MacX from the 
Apple menu to see how much memory is available. If less than 100K is free, quit MacX, 
choose Get Info from the File menu, and increase the MacX application memory size in 
the Get Info dialog box. If MacX appears to have sufficient memory, check About MacX 
occasionally as you start up new clients. You may find that MacX needs more memory to 
run certain clients or to handle the number of clients that you typically run at the same time. 

The connection came up halfway and then failed. 

The remote host will not allow you to connect. Call your system administrator for assistance. 

The destination host is not responding to address resolution 
requests . 

Either the host to which you want to connect or an intervening gateway (or router) is down. 
Call your system administrator for assistance. 

The dot-notation address has a syntax error. 

The host IP address that you entered for your remote command is probably wrong. While 
holding down the Option key, choose that remote command from the Remote menu and 
click the Hosts button in the New Remote Command dialog box. When the Connection 
Settings dialog box appears, select MacTCP and check the IP address that you typed in 
the "Host Name or Address" box. If you're not sure whether the address is correct, see 
your system administrator. 

The IP or LAP configuration resource is missing. 

One of the AppleTalk network drivers, such as the EtherTalk or the TokenTalk® driver, 
is either not selected or improperly installed. To identify the problem, follow these steps: 
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1. Open the control panel and see which network icon is selected. (See "Configuring the 
MacTCP Driver," earlier in this module, for detailed instructions.) If an icon is selected, 
go to step 2. 

If no icon is selected, follow the instructions in "Selecting Your Network Type" to select 

the correct one. Next, follow the instructions in "Configuring the MacTCP Driver." Now 

try starting MacX again. If the error recurs, see your system administrator. 

If no icons appear in the control panel, then your System Folder does not contain any 

network drivers. To install the EtherTalk driver, consult the Apple Ethernet NB User's 

Guide. Next, install and configure the MacTCP driver as described earlier in this 

module. 

2. If an icon is selected, its corresponding driver in your System Folder may have become 
corrupted or been improperly installed. Follow the instructions in the user's guide for 
that AppleTalk driver to reinstall it. For example, if you selected the EtherTalk driver, 
refer to the Apple Ethernet NB User's Guide. Be sure to use the installer program to 
reinstall the driver, rather than simply dragging a new driver into your System Folder. 
After reinstalling the driver, go to the control panel and select the network icon again. 

The manually set address is configured improperly. 

The IP address in the control panel is missing or incorrect. First, check the control panel 
to verify that an address exists. For instructions, see "Configuring the MacTCP Driver," 
earlier in this module. Next, contact your system administrator either to get an IP address 
or to verify that the existing address is correct. 

The specified command action was not completed within the 
timeout period. 

Too much time has elapsed for your command to be performed. Probably the network was 
busy and took so long to transmit your command that MacTCP assumed that your connec- 
tion had dropped. This condition is usually temporary, so try reissuing your command. 
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The TCP connection went down. 

The communications path between you and your host computer has been broken. For 
example, the gateway to your host may have shut down, your host may have shut down, 
or the coaxial cable that connects your Macintosh to your Ethernet network may have come 
loose. Since the disconnection might be temporary, first try reconnecting to the host with 
which you lost contact. After trying to reissue your remote command a few times with no 
success, check the network cable at the back of your Macintosh to ensure that it is firmly 
attached. If it is, call your system administrator for further assistance. (Also see "Network- 
Related Problems," later in this section.) 

There are too many TCP and/or UDP streams open to open 
another . 

You have opened the maximum number of TCP/IP connections (64) that can be established 
at the same time. In other words, you cannot open another host session until you close 
an existing connection. Close an existing connection (by logging off a host computer on 
the TCP/IP network, for example) if you want to establish a new connection. 

This domain name does not exist . 

The domain name server does not recognize the domain name specified in the MacTCP 
administrator dialog box. Verify that you have entered this name correctly; you may have 
misspelled it. (The section "Specifying Settings in the Administrator Dialog Box," earlier 
in this module, explains how to display the MacTCP administrator dialog box.) 

Unable to initialize the local network handler. 

This error can occur for a variety of reasons. For example, you may have filled in the 
MacTCP administrator dialog box incorrectly, or there may be something wrong with your 
Ethernet connection. Make sure that you have configured the MacTCP driver according to 
the instructions given earlier in this module. Verify that your EtherTalk card and software 
are installed correctly and that the jumper on your EtherTalk card is set for the right type 
of cable. (Also see the next section, "Network-Related Problems.") 
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Network-related problems 

If one of the scenarios in the following list describes a problem that you're having, the 
problem could be related to the network hardware or software that you're using. 

The Control Panel (version 6.0.x) or Control Panels folder (version 7.0) is missing. 

The Control Panel or Control Panels folder is present on all startup disks. If you're using 
more than one startup disk, your Macintosh may switch to a disk without the Control 
Panel or Control Panels folder installed. The icon of the current startup disk appears in 
the upper-right corner of the desktop. 

Use the Installer application from the System Tools disk (version 6.0.5 or a later version) 
to update your System file. The Installer automatically reinstalls the Control Panel or Control 
Panels folder. 

The MacTCP icon is missing from the Control Panel (version 6.0.x) or Control 
Panels folder (version 7.0). 

In this case, one of the following conditions exists: 

■ You don't have the EtherTalk 2.0 software installed correctly on your startup disk. See 
the documentation for the Ethernet card that you are using. 

■ The MacTCP icon has been removed from your System Folder. You must reinstall the 
MacTCP software. See the Installation part of the Network Services User's Guide. 

■ Your startup disk has the wrong version of the Control Panel or Control Panels folder. 
You must use version 3.1 or a later version. (The version number appears in the lower- 
left corner of the Control Panel in version 6.0.x) Use the Installer application from the 
System Tools disk (version 6.0.5 or a later version) to update your System file. The 
Installer automatically reinstalls the Control Panel or Control Panels folder. 
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You can't select the MacTCP icon in the Control Panel (version 6.0.x) or Network 
panel (version 7.0). A message appears, advising you that the network package 
has not been installed correctly. 

The EtherTalk 2.0 software has not been installed properly on your startup disk. See the 
documentation for the Ethernet card that you are using. 

Neither the EtherTalk icon nor the Ethernet icon appears in the Control Panel 
(version 6.0.x) or Network panel (version 7.0) after you click the MacTCP icon. 

One of the following conditions exists: 

■ You don't have the EtherTalk 2.0 software installed correctly on your startup disk. See 
the documentation for the Ethernet card that you are using. 

■ The EtherTalk file has been removed from your System Folder. You must reinstall the 
EtherTalk 2.0 software. See the documentation for the Ethernet card that you are using. 

■ There is no Ethernet card in your Macintosh, or the card is not working properly. If a 
card is installed, see its documentation. 

Two or more EtherTalk or Ethernet icons appear in the Control Panel (version 
6.0.x) or Network panel (version 7.0) when you click the MacTCP icon. 

One of the following conditions exists: 

■ You have multiple Ethernet cards installed. The number in parentheses next to each 
icon's name identifies the slot containing the card. 

■ Earlier versions of EtherTalk software exist on your startup disk. Earlier versions are 
identified by single-arrow icons; icons for version 2.0 (or later versions) are identified 
by double arrows. PATHWORKS™ for Macintosh® requires that you use EtherTalk 
version 2.0. See the documentation for the Ethernet card that you are using. 

If you want to remove the previous version of EtherTalk, find its icon in the System 
Folder and drag it to the Trash. 
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You can't select the EtherTalk or Ethernet icon in the Control Panel (version 
6.0.x) or Network panel (version 7.0). A message appears, advising you that an 
error occurred while trying to install EtherTalk. 

You did not start your Macintosh with an EtherTalk startup disk, or the disk that you used 
has become damaged. Try reinstalling the EtherTalk 2.0 software. See the documentation 
for the Ethernet card that you are using. 

You are unable to select an EtherTalk or Ethernet icon in the Control Panel 
(version 6.0.x) or Network panel (version 7.0) to switch the network connection. 
A message appears, advising you that the connection cannot be changed now, 
or that doing so will disrupt a critical service that your computer provides (such 
as an AppleShare® file server or a router). 

If you can't switch the network connection, quit all applications and try switching the net- 
work connection again. If you still can't switch network connections, and you don't mind 
disrupting services that your computer provides or is using, shut down your Macintosh. 
Then restart your computer, using a startup disk that permits network-connection changes. 
Finally, try switching the network connection again. 

Your Macintosh computer "hangs" (does not respond to the mouse and keyboard 
actions). 

Your Macintosh may hang for a minute or so when you select an EtherTalk or Ethernet 
icon, or when you start up your computer. The computer can hang if it is not correctly 
connected to the Ethernet cable or the Ethernet card is not configured correctly. See the 
documentation for the Ethernet card that you are using. 
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The Connection Settings dialog box does not list any network services or does 
not list the service that you want. 

■ If no network services appear, check the physical connection between your Macintosh 
and the network. See the suggestions later in this section for checking your network. 

■ If a particular service does not appear, the service may be in a different zone, malfunc- 
tioning, switched off, or disconnected from the network. There may also be trouble 
in the network cables between your Macintosh and the missing service. See the 
suggestions for checking your network in "Ethernet Troubleshooting Checklist," later 
in this section. You can also contact your system administrator to find out if there are 
known problems with the network. 

■ If you switched the network connection in the Control Panel (version 6.0. x) or Network 
panel (version 7.0), as described earlier in this module, while the Connection Settings 
dialog box was open, the services listed in the dialog box may not have been updated. 
Close the Connection Settings dialog box and reopen it to view the services on the 
newly selected network. 
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Ethernet troubleshooting checklist 

Here's a checklist to consult whenever you're having trouble with the Ethernet network: 

■ Are all cables secure? 

Make sure that the network cable to your Ethernet card is secure at all connections. 
Also check the network cable to the service that you're trying to use. Contact your 
system administrator if you are uncertain about cable configuration. 

■ Is the problem really related to the network? 

Sometimes a problem that seems to be related to the network is actually related to the 
device or application program that you're using. The manual for the device or applica- 
tion may be helpful. 

■ Is your Ethernet card installed and set correctly? 

Shut down your Macintosh and make sure that the Ethernet card is firmly seated in its 
slot. Also, make sure that any jumpers and switches are set properly. See the documen- 
tation for your Ethernet card. 

■ Is the application that you want to use available on your network? 

You may have more than one network to which you can connect. Use the Control 
Panel (version 6.0. x) or MacTCP control panel (version 7.0) to select the proper 
network connection. For instructions, see "Selecting a Network" in Chapter 2 of the 
MacX User's Guide part of this binder. 
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The DECnet™ Connection Tool allows you to make a connection between MacX™ and 
a DECwindows™ client by using the DECnet protocols. 

This reference module tells you how to confirm that DECnet is properly configured and 
then describes the DECnet connection settings that allow you to use the DECnet Tool with 
MacX. This module also lists alert messages that may appear while you are using the 
DECnet Tool and provides possible explanations and solutions. 
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What you need 



The Installation part of the Network Services User's Guide provides installation procedures 
for PATHWORKS™ for Macintosh and describes all of the components, including those 
related to the DECnet Connection Tool. The following list summarizes the software com- 
ponents required for the DECnet Connection Tool and indicates where each component 
must be installed. 

■ Macintosh Communications Toolbox— installed in the System file if you're using system 
software version 6.0. x. If you're using version 7.0, the Macintosh Communications 
Toolbox is installed automatically in your Macintosh system. 

■ DECnet Tool— installed in the Extensions folder (version 7.0) or Communications 
Folder (version 6.0.x). 

■ DECnet/Mac — installed in the Extensions folder (version 7.0) or Communications 
Folder (version 6.0.x). 



Confirming your DECnet configuration 

Before you can use the DECnet Tool with MacX, you must have DECnet properly config- 
ured as described in the Network Services User's Guide. Your system administrator has 
probably already provided all the information necessary to configure DECnet, such as 
assigning your computer a valid node number. However, you may have to establish many 
of the settings yourself by following the procedures in the Network Services User's Guide. 

You can confirm the state of your DECnet configuration by opening the Control Panel 
(version 6.0.x) or DECnet control panel (version 7.0) and checking the settings displayed 
in its window. 
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If you're using version 7.0 

To open the DECnet control panel: 

1 Choose Control Panels from the Apple (#) menu. 

The Control Panels window opens. 
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2 Double-click the DECnet Control icon. 

The DECnet control panel appears. 
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Confirm that the Network State is On and that other configuration information 
in the DECnet control panel is valid. 

If DECnet does not seem to be properly configured or you have any questions about your 
configuration, ask your system administrator for help or see the Network Services User's 
Guide for more information. 

Close the DECnet control panel. 

Close the Control Panels window. 

If DECnet is properly configured, go to "DECnet Connection Settings," later in this module, 
to learn how to use the DECnet Tool with MacX. 
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If you're using version 6.0.x 

To display the DECnet settings in the Control Panel: 

1 Choose Control Panel from the Apple (#) menu. 

The Control Panel window opens. 
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2 Select the DECnet Control icon from the group of icons on the left side of the 
Control Panel window. 

You may need to use the scroll bar to find the icon. 

The Control Panel displays the DECnet Configuration settings. 
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Confirm that the Network State is On and that the other DECnet configuration 
information in the Control Panel is valid. 

If DECnet does not seem to be properly configured or you have any questions about your 
configuration, ask your system administrator for help or see the Network Services User's 
Guide for more information. 

Close the Control Panel window. 

If DECnet is properly configured, go to the next section, "DECnet Connection Settings," to 
learn how to use the DECnet Tool with MacX. 
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DECnet connection settings 



You can use the DECnet Tool to specify a connection to the VAX™ computer to which 
you want to connect. 

To access the Connection Settings dialog box, you click the Host button on the right 
side of the MacX New Remote Command dialog box. See your system administrator for 
the values you need to supply in the New Remote Command dialog box. (For information 
on the New Remote Command dialog box, see Chapter 3 in the MacX User's Guide.) 

To use the DECnet Tool: 

1 Start MacX and choose New Command from the Remote menu. 

The New Remote Command dialog box appears. 
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2 Fill in the New Remote Command dialog box with the settings your system 
administrator gave you. 

The settings include the type of command you use to connect to the VAX, how the data 
is displayed on your screen, your user name, and your password. 
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When you've finished entering the values in the New Remote Command dialog 
box, click the Host button. 

The Connection Settings dialog box appears. 

Choose DECnet Tool from the Method pop-up menu, in the upper-left corner of 
the dialog box. 





$miki himlam Tool 
flppleTalk HDSP Tool 
RppleTalk-DECnet Tool 
RppleTalk-LRT Tool 

CTERM Tool 




Connection S« 




II Method: 


DECnet Tool r ., 


( Cancel ) 




-/MacTCPTool * 

Serial ISBN lt>t>\ 













The lower part of the dialog box changes to display the settings for the DECnet Tool. 

In the Node Names list, select the name of the node that offers the service you 
want to use. 

The name you selected appears in the Node box. (You can also type the node name 
directly into the Node box.) 
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6 



Click the OK button. 



The Connections Settings dialog box disappears and you return to the New Remote 
Command dialog box. 

7 In the New Remote Command dialog box, click the Execute button to start the 
connection. 



Troubleshooting hints 

If problems arise while you are using the DECnet Tool to communicate with a host on a 
DECnet network, your Macintosh displays one or more of the error messages listed in 
this section. Each message appears in an alert box similar to the one shown in the 
following figure. 




The remote command "MyMotif" could not be 
executed via the tool "DECnet Tool". Creation of the 
remote command stream failed. 



Problems can occur in different places while you are making a DECnet connection. If 
your Macintosh is connected to a wide area network, many alert messages may appear. 
Some of the common messages, and solutions to the problems indicated by the messages, 
are listed in this section. In many cases, however, you will need to contact your system 
administrator for a description of the problem and a possible solution. 
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If one of the following alert messages appears while you are using the DECnet Tool, try 
opening a new connection. If you still have problems, contact your system administrator. 

A third party has terminated your DECnet link. 

An application or program that you are using, other than MacX or DECnet, broke the 
connection. Try again to make the connection. 

An invalid username was specified for the DECnet connection. 

The user name that you entered in the Connection Settings dialog box is not correct. Open 
the Connection Settings dialog box and make sure that you've entered your user name 
and password correctly. If you have, ask your system administrator if you are using the 
correct user name. 

Either your username or password is incorrect . 

The user name or password (or both) that you entered in the Connection Settings dialog 
box are not correct. Open the Connection Settings dialog box and make sure that you've 
entered your user name and password correctly; then try opening the connection again. 
If the problem persists, ask your system administrator if you are using the correct user 
name and password. 

No resources for a new link. 

The VAX to which you are trying to connect does not have enough resources, such as 
available memory, to establish a new link. 
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The DECnet link was disconnected. 



The DECnet task name was not known at the remote node . 

The task or service (such as VMS™ Mail) to which you are trying to connect could not be 
located. Open the Connection Settings dialog box and make sure that you've correctly 
entered the name of the task or service. (See "DECnet Connection Settings," earlier in 
this module.) 

The remote DECnet application aborted your link. 

The VAX computer you are connected to is using an application that in turn terminated 
the link. 

The remote DECnet node has insufficient resources for this 
connection . 

The VAX to which you are trying to connect does not have enough resources, such as 
available memory, to establish this connection. Try again to make the connection. 

The remote DECnet node is not reachable . 

The node to which a connect request has been sent is unreachable. 

The remote DECnet node is shutting down. 

The destination Session Control is in the SHUT or RESTRICTED state and therefore cannot 
handle incoming connect requests. SHUT and RESTRICTED refer to conditions imposed 
by the system administrator on incoming connections to the VAX. 
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The remote DECnet node terminated the link. 

The remote DECnet user cancelled or aborted your connect 
request . 

The user you are trying to connect with is having a problem establishing or maintaining 
a connection, thereby disrupting your connection request. 

The remote DECnet user disconnected the link. 

The user at the destination terminated the link. Try to make the connection later. 

The remote DECnet user disconnected without giving a reason . 

The remote DECnet user has insufficient resources for this 
connection . 

The user you are trying to connect with does not have enough resources to establish this 
connection. Resources include the correct user name or password. 

The remote system exceeded the available network links . 

The destination system does not have sufficient resources to handle a new logical link. 

Your DECnet connection was rejected because of an invalid 
user name or password. 

The user name or password (or both) that you entered in the Connection Settings dialog 
box are not correct. Open the Connection Settings dialog box and make sure that you've 
entered your user name and password correctly; then try opening the connection again. 
If the problem continues, ask your system administrator if you are using the correct user 
name and password. 
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Your DECnet connection was rejected because of an 
unacceptable account . 

Your DECnet connect request contained unacceptable account information. This informa- 
tion helps administrators log time spent on the VAX for billing and other financial tracking. 
Account information generally consists of a user name, password, and some text name 
such as a project name that is specific to the account. Confirm that your account infor- 
mation is correct. 

Your DECnet is turned off. 

Your DECnet software is not running. Open the Control Panel (if you have system soft- 
ware version 6.0. x) or the DECnet control panel (if you have system software version 
7.0) and make sure that the DECnet State is turned on. 
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MacX™ Keyboard Mapping 

Quick Reference Card 
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This Quick Reference Card presents the different keyboard mappings 
available for use with MacX. Four different mappings are provided: 

■ Positional Mapping for Apple® (ADB) Extended Keyboard 

■ Inscriptional Mapping for Apple (ADB) Extended Keyboard 

■ Apple Standard (ADB) Keyboard Mapping 

■ Macintosh® Plus Standard Keyboard Mapping 

Each of the mappings changes the meaning of certain keys on your keyboard 
to match keys on the VT300 keyboard. Two of the mappings — Positional and 
Inscriptional — reconfigure the Apple (ADB) Extended Keyboard. 



The Positional mapping reassigns keys on the Apple (ADB) Extended Key- 
board to match as closely as possible their position on the VT300 keyboard. 
The Inscriptional mapping reassigns keys on the Apple (ADB) Extended Key- 
board to match their meaning as closely as possible to VT300 keys. The two 
mappings for the Standard keyboards reconfigure the Macintosh keyboards to 
perform VT300 functions when you use the Command key with keys on the 
numeric keypad. 

See the MacX User Update for additional information, including how to install 
the keyboard mappings. 
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Option with arrow keys 



Note: This chart shows the 
default mappings for the arrow 
keys when used by themselves 
and when used with the 
Option key. See "Arrow Keys 
Mapping" on this card for 
additional information. 
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Keys marked with an asterisk indicate keys on the numeric keypad. 
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Positional Mapping for Apple (ADB) Extended Keyboard 
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Note: This chart shows the 
default mappings for the arrow 
keys when used by themselves 
and when used with the 
Option key. See "Arrow Keys 
Mapping" on this card for 
additional information. 
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Note: This chart shows the 
default mappings for the arrow 
keys when used by themselves 
and when used with the 
Option key. See "Arrow Keys 
Mapping" on this card for 
additional information. 



Command with arrow keys . . .and keypad 



t 

Prev 
screen 



5 

Help 



Do 



Next 
screen 



Keys marked with an asterisk indicate keys on the numeric keypad. 



Enter 



Inscriptional Mapping for Apple (ADB) Extended Keyboard 
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Note: This chart shows the 
default mappings for the arrow 
keys when used by themselves 
and when used with the 
Option key. See "Arrow Keys 
Mapping" on this card for 
additional information. 
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Arrow Keys Mapping for All Macintosh Keyboards 



Note: This chart shows the default mappings for the arrow keys when 
used by themselves (simulating the Alt [meta] key, control key, and 
middle and right buttons on a three-button mouse) and when used 
with the Option key (acting as regular arrow keys). By changing the 
Mouse Buttons Simulated By option in the Miscellaneous Preferences 
dialog box, you can reverse the mapping so that the arrow keys act as 
regular arrow keys when used by themselves and simulate the Alt 
(meta) key, control key, and middle and right buttons on a three- 
button mouse when used with the Option key. The relevant portion 
of the Miscellaneous Preferences dialog box appears to the right. 
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